General Tips

What ToDO-lists have in common with class interfaces

NOTE: I have completely forgotten that I had started this blog! A couple of days ago, I shared with a new colleague the documents on software quality essentials that I made two years ago for our laboratory, and suddenly a thought of this blog popped up.

During my work, I do quite some refactoring and documenting of the legacy code. The code pieces represent implementations of scientific algorithms by former PhD students, mainly with the background in mathematics. That means: only vague understanding of the object-oriented methodology, prefering the speed of development and reaching “it’s working” stage to the code quality, and less than minimal level or absolutely no comments or documentation.

I find this very unfortunate that there is only a little attention to the software quality aspects for mathematics and physics students in general. Very unfortunate, because for the next person who comes to work on and extend the code it takes a huge amount of effort to understand what is done and how it is implemented (assuming the why is clear from the tool/library purpose itself).

In this case, fortunately this student is me, and I am investing the effort in making the code better (which is absolutely undervalued by my supervisor and current colleagues, and makes it even harder). But so often a next person spends a huge amount of time to understand the code, then reuses it as it is. Then the next person after that one will again need to invest a lot of time and efforts, and the next, and the next. Just writing the good code from the very beginnning, or taking the time to clean it up and document it at the end of a projects that used it will pay off multiplied in future. I believe in leaving everything in a better state than we found it, so I do it anyway, despite the lack of support in the present.

This time, I have been struggling with understanding a class interface, and I decided to share my insights here. I have found a wonderful analogy in a TEDx talk! ( Surprise-surprise! 🙂 ).

In his wonderful talk at TEDx Claremont Colleges, David Allen demonstrates a fundamental mistake which many people make when they write ToDo-lists. They write NOUNS. “Mother”, “dog”, “kids”. Then, an hour later you look at the list and you have no idea what you actually wanted to do. Certainly, that was something about the kids. Pick them up from school? Take them to a movie? Talk to them about the plans for holidays? You spend a lot of extra mental effort each time when you look at such a ToDo-list. It does not serves its purpose of being a reminder of the ACTION you want to take.

Well, a class interface is essentially the same as a ToDo-list! It specifies the list of OPERATIONS (actions) the object of this class can perform. Thus, writing it in nouns would generate the very same struggle as in ToDo-list. Let’s show it on example (the return types and arguments are omitted for clarity):

class Car {
public:
	Doors();	
	Belts();
	Engine();
	WindshieldWiper();
	Mirrors();	
	drive();
}

Obviously, the class Car has something to do with all of these things. But take Engine(). Is it actually startEngine()? Or maybe it is serviceEngine()? Maybe you take a look to the implementation (and this is already a sign of bad code quality) and realize that this method is actually checkEngineAndMakeSureOilLevelIsOK()? 🙂 And the same with every other method in the class: you need verbs that clearly explain the performed operation. And our Car will become:

class Car {
public:
	closeDoors();
	plugBelts();
	adjustMirrors();
	turnOnWinshieldWiper();
	startEngine();
	drive();
}

I would say that the only exception from these rule are properties and getter/setter methods. For properties in C# or Objective-C, you don’t even think about them, the compiler generates them for you automatically. And for a variable named x, the getter may be getX() or simply x(). The setter, however, should be setX(). Again, in some languages this is done automatically, and all you need to write is

	obj.x = 5;
	drawTickMark(obj.x);

In all other cases, use the rule above. Have a verb in the method name that tells you the action, and try to make the performed operation as clear as possible from the method name. Bonus point: add a comment that says it in a plain text. But we’ll talk about the comments and documentation in another post (in the meanwhile, you can check the document I have written for the lab about the documentation essentials).

Enjoy,
and write the good code!

P.S. And now you can watch the full talk “The Art of Stress-Free Productivity” by David Allen:

Advertisements
Standard

2 thoughts on “What ToDO-lists have in common with class interfaces

  1. Pingback: Public interfaces in C++ | OOP Tips

  2. Pingback: Entity naming style | OOP Tips

Leave a Reply

Fill in your details below or click an icon to log in:

WordPress.com Logo

You are commenting using your WordPress.com account. Log Out /  Change )

Google+ photo

You are commenting using your Google+ account. Log Out /  Change )

Twitter picture

You are commenting using your Twitter account. Log Out /  Change )

Facebook photo

You are commenting using your Facebook account. Log Out /  Change )

Connecting to %s