subbu.org

Hold on for just a sec. Let’s say you wrote some piece of code that does something useful. You wrote some tests to verify that this code works, and those tests pass. You are almost ready to submit your code to whatever source control system you are using, except for some cleanup that you wanted to do. Here is a choice - you can either do the cleanup, rebuild, retest, and submit. Another choice is to quickly insert some TODO comments, make sure the code compiles, and check it in. You can always come back and do that cleanup - right? May be. The odds of coming back to that task are not very high. I would argue that even if you get a chance to clean up, the quality of the code will not be the same as keeping the code clean in the first place. The kind of things that fall prey to the mindset of the “let me check-in�? camp include TODO/review comments, exceptions, localized log messages, javadoc comments, unused code/imports etc. The cost of maintenance
of such code usually suffers in the long run, not to mention frustration of future developers working on the same piece of code.

Here are some examples. You may have seen worse/better. The text in italics below each example is mine.

// TODO: Does this work?

If not, why? Why did you think this code does not work? Why not elaborate?

// Something wrong here. Hmmm.

Be more specific what you think is wrong here, so that the poor soul fixing bugs in this code can understand.

// Ask Bob why this thing does not work
/*
some commented out code
*/

Instead of leaving a comment like this, why not open a bug in your bug system to keep track of this.

Some of these comments do probably make sense on the day they were written, but not afterwards. People do move on to other projects. Worse yet, sometimes the developer may not recall why he/she added a given comment. Here is another example of a worse kind.

// Send false now
doBlah(xx, yy, true);

The comment says that the method should be passed a boolean false, but the actual code is passing a true. Which one is right - the code or the comment? The code is most lilely right, but why did the comment say otherwise? Most likely, the dev thought that he/she should pass a false, but had to send a true for some reason. Without explaining why, it would be hard for future developers to maintain this code. My point is that, good comments can be used to improve the quality of code, and TODO/review comments like the above do the opposite. Mistakes like this usually get picked up during code reviews, though, but some times end up in production code.

Take javadoc comments. I noticed a similar “let me check-in” attidue compromising the quality of documentation comments. I have heard developers saying that they prefer documentation towards the end of the development phase. Their rationale is that code will be more stable by then, and they don’t need to keep correcting the comments. But I question this rationale. I think the best time to add documentation comments is when you are thinking about implementation, or actively making design/implementation choices. During that time, you will have more to talk about the code. Once the coding is complete, and is well-tested, you may have less to say about the code. So, I would argue that documentation comments should be added right at the start of coding, and must be improved upon during coding. Of course, this is not a silver bullet solution to get documentation comments reflect the code, but it is better than adding comments just for the sake of adding comments at the end of the coding phase.

Writing working code is not that great, writing clean and maintainable code is.