Many developers hate documenting their code: They view writing comments a nuisance, something that slows them down. All they want to do is get the darn code to run; comments just mess-up the code and — behold! — are for wimps, anyway.

Sometimes even followers of this school of thought write comments, but these comments are frequently a mixture of self-indulgence, inside jokes or just plain insults:

Then there are folks who take the exact opposite position. They want comments everywhere. They believe that comments should be of such a density, that by just reading the comments they would get a perfect understanding of the whole system. Never would they have to look at such ugly things as — behold! — source code again.

Like it or not: I have observed that many of the highly gifted developers belong to the first group.

But let’s face it: neither position is right. As professional software developers we need to understand that we have an obligation to preserve the value that we create. Good comments do help understanding the code and thus improve maintainability and we are in maintenance mode most of our lives. Like the old saying goes: “Be nice to the next guy”; and often that next guy is you (or me).

On the other hand, crafting good comments is hard and time consuming and as professional software developers we also have an obligation to spend the resources of our companies or clients prudently. Therefore, we need to strike a balance: sometimes it is best to leave the nitty-gritty details for the code.

My rules of thumb so far have been:

1. Focus on good layout and self-explanatory identifier names.
2. Explain the WHAT and not the HOW.
3. Comment surprises; that is, unexpected/unusual things.
4. Comment all non-private parts (public, protected, default)
5. The more public, the more detailed the documentation has to be.

I used to defer writing API documentation comments as long as possible. My reasoning was that otherwise I would have to update/rewrite the API documentation while iteratively developing my code, which I considered a big waste of time and energy. But I’ve changed my mind completely in this respect.

I strongly believe that writing the API documentation before doing any coding is a great benefit. By clearly spelling out the purpose of a piece of code, developers engage in a brainstorming session with themselves that leads to further insights. Until this purpose cannot be stated concisely there is no point in doing any coding. Let me repeat that: If you cannot crisply describe WHAT a method or class is supposed to do, you shouldn’t start implementing it. Granted, most developers do have at least a partial model in their mind before they start coding. If they would also write it down, they could win in several ways.

Naturally, even API documentation comments need to be developed iteratively and often need some fine-tuning during the course of implementing the API. In fact, the process is very similar to test-driven development: One of the biggest benefits of TDD is that by writing tests before doing any coding, you imagine (and in fact see and experience) how the interface is used by clients early on; that’s valuable feedback which helps getting interfaces better. The same holds for the WHAT of a method or class as well.

The notion of writing comments or documentation before doing the coding can be extended to the implementation of a routine as well. In his landmark book, “Code Complete”, Steve McConnell describes a comment-first process for implementing a routine called “Pseudo code Programming Process”: You start by typing in the high-level steps that a routine takes, in plain English, using vocabulary from the problem domain:

Once your are satisfied with your pseudo code, you fill in the real code. As a final step, you turn the original pseudo code into comments — voilà!

[Note: I know that this example is a little bit contrived. A cooler implementation of CalculateTaxRate() would return a tax rate of zero in case the income is below the threshold. This would result in shorter, branch-free code.]

Writing good comments is essential for every professional software developer. Since writing comments is hard, it is usually left out if it is considered an afterthought, especially under deadline pressure. If it is done upfront, it can serve as a valuable design tool that yields great documentation for free.

I was so proud: after I had gotten rid of some minor compile-time issues (ie. typos), my unit tests ran over my newly written code without any errors. Granted, the changes I made comprised less than 500 lines, but still, it meant something to me. Feeling happy and content, I hummed R. Kelly’s “The World’s Greatest” while carrying on with other work.

A few days later, I wrote some black-box tests and — to my big surprise — I got a couple of “fails”. After some debugging, I found more than five bugs in the code that had passed my unit tests so nicely. I was completely puzzled. What went wrong? Why didn’t my unit tests catch these trivial bugs?

As it turned out, I forgot to register my test code with the CppUnit test framework, so my tests were not executed at all! Once I had added the missing line

to my test suite class, all five bugs surfaced in an instant. I was so angry! My first reaction was to curse CppUnit: with JUnit this would not have happened. I would have used the @Test annotation and my test would have been auto-registered — unless I had forgotten to tag it with the @Test annotation…

Later that day, I realized that the actual mistake was a violation of Steve Maguire’s powerful principle: “Step through every line of code that you added or changed with your debugger”. Had I set a breakpoint in my code, I would have seen that it was never executed.

Years ago, I used to be a passionate follower of this principle, but somehow unlearned it, largely — I presume — due to the rising unit testing hype. Don’t get me wrong: I think that unit testing is great (and black-box testing is great, too), but it is no replacement for single-stepping through your code.

Reviewing your own code is good, but actually stepping through your code is much cooler. The cursor showing the next statement to be executed focuses your attention and you really experience the program flow instead of having to make guesses about it. Further, you have all the data available and you can even modify it. You can invoke functions from your debugger (e. g. ‘call myfunc()’ in gdb), play with different combinations of parameters, member variables and the like, re-execute just executed code without restarting the debugger by setting the “next statement to execute” a couple of lines up. Probably the biggest benefit is that you get a deeper understanding of your code: maybe you step over a library call that works as expected but takes two seconds to execute; or you observe that you unnecessarily visit the remaining elements of a collection after you found what you’ve been looking for — no unit test would give you this kind of insight.

Often, it is difficult to unit test for certain failure causes, like malloc() returning NULL on out-of-memory conditions:

How would you unit test that? Such error handling code is usually left untested and is the reason why so much software crashes under heavy load. While you’re in a debugger, testing is easy: just set the “next statement to execute” to the error-handling code (right before stepping over the call to malloc), step through it and convince yourself that it works as expected. Again, how would you unit test that? Answer: factor out the error-handling code:

Now, you can call your error handling code from your unit tests. Still, testing the code by using the debugger is easier, doesn’t require any context set-up and gives more insight.

It helps, of course, if you write your code such that debugging is as painless as possible. A line like this is fine, of course:

but writing it like this is (probably) more readable and you can inspect (and alter) intermediate values in your debugger:

If you think this is too much typing, get better at typing and/or get yourself a better editor. If you think this wastes code, bear in mind that we don’t live in the 1970s anymore. If you think that you can always step inside convertSensorReading() and inspect/change the parameters there, you are right, at least as long as you have access to the source code of the function you want to step into.

Macros are bad since you cannot step into them. Use them only if you have no other choice; instead prefer (inline) functions and template functions: they come with the same efficiency advantages and you get type-safety and debuggability as a bonus.

And, speaking of the preprocessor, stop using #define’d symbolic constants: all preprocessor symbols are inlined during the preprocessor phase and I don’t know of any debugger that can resolve their values. Instead, use enums or, even better, const variables:

Mouse over MIN_COUNT in your debugger and you will see nothing; mouse over MAX_COUNT and you will get “the answer” ;-)

Automated unit tests are great, but stepping through your code gives quick feedback and a lot of insight into what is happening at run-time. Sometimes, hard-to-write unit tests can be avoided by consequently following the “step through all of your code” paradigm. As a simple guideline write unit tests — if you like — before starting with the implementation. Then single-step your code by executing your unit tests in a debugger and watch your step.