Developer Aspirations

YAPB - Yet Another Programming Blog



January 2011

Why You Should Comment

by Colin Miller, on Comments, Design, development, Musings, requirements

I almost wonder why I would even have to make a post like this. It seems like common sense doesn't it? When you write new code, you should write comments with your code to explain what the code is doing. Sometimes the comments should be inline for a tricky algorithm, but often it's sufficient to place comments at the start of a method/function or class just to describe what it is so that the reader doesn't need to step through your code to understand what it's doing. When you make significant changes to a method/class, you update the comments. Seems simple and pretty obvious doesn't it?

Then why don't more people add useful comments to their code? Often I'll see this:

[caption id="attachment_383" align="aligncenter" width="603" caption="Ignore the fuzzed out bits, NDA and all. Note however that there's a default comment made by the IDE (IntelliJ in this case) and that the IDE itself even recognizes that the default comment should be changed by marking it yellow. Yet people still ignore this and just leave it be."]Evil Default Comments[/caption]

The fact that this BugzillaGrouper class was created on October 11th, 2011 at 5:01:37 PM in IntelliJ IDEA tells me... well not really anything about the class itself. The IDE even recognizes that this is just the default template comment and marks it as a warning (signified by the yellow bar on the right) as something that should be changed. Yet many developers will just ignore this and move on to writing code rather than ever changing the default comment. This brings up two points that I'd like to make.

Firstly, default comments are bad. They leave the developer with a false sense of documentation. I mean, the code has a comment on it, it'll even generate documentation if you run it through JavaDoc or a similar tool. However, that documentation is worthless. The default comment is less than worthless because the developer sees that there is something up in the comment field and just ignores the fact that it's a useless bit of fluff. If no default comment were in place, the developer might look at his/her code and thing "Gee, I don't see any of those green comment boxes at all. This file seems really short. I should add a succinct, well thought-out, and useful comment so that other developers (or even myself) will later look at this file or the generated documentation and be able to easily understand the purpose and usage of this class. Perhaps I'll provide an implementation example if I'm feeling randy." Ok, no developer really thinks that, but they should. With a default comment in the code, the chance they'll think about comments at all goes down significantly.

Second, when people do write comments, they often don't write very good ones. Often it goes along the lins of "A BugzillaGrouper is a class that implements the Grouper interface." Well that's almost as bad as the default comment. Heck, I could figure that out from the class signature, and by reading less words even. What's really the purpose of the class? It implements an interface, so that means it's performing the function of the interface but in an implementation specific way. What is that? For example: "The BugzillaGrouper in this instance is a Grouper that groups incoming report data by the bugzillaId. It automatically splits apart bugzillaId's that are comma separated into multiple ID's. Unlike other Groupers that aggregate test result counts of similarly grouped items, the BugzillaGrouper only produces a set of distinct bugzillaId's as it's primary output. The output is a JSONArray in the following form:..."

I'm not going to list the actual form of the JSON output but I think you get the idea. The main part of the comment is only 4 sentences and took just a few minutes to write. However, the comment has some useful information about what it does specifically in relation to the interface it implements. It also describes how it is different from other implementations. An example of the output (which is different than what most groupers would produce) let the user's of the class know exactly what to expect without having to step through the code itself for the output format.

Comment Driven Development

I'm already an avid fan of Test Driven Development. Another popular idea making the rounds is Comment Driven Development. I think these two can be used synergistically (one more for buzzword bingo!) to help with an agile development process. Also, it will leave a project with some (hopefully useful) documentation.

The main idea is to write the comment to a method/function/class before writing the code. If you're unable to write an explanatory comment before coding, then you probably don't know the problem domain of that piece of code enough to really be writing the implementation for it. Also, when you write the comment first, you're actively thinking about what that piece of code should be doing. You can work out the design in your head, similar to how you can work out a design by writing a test before your code. Ideally, those two processes can intertwine and work off of each other.

For example, you would first start out by writing the comment to a function you want to implement. Having that basic written description of what the function does, you write a test for the implementation. Perhaps you find some sort of problem with how the actual implementation would work (maybe you need to split it into multiple functions or change some signatures around). This causes you to go back and modify your comment based on your new assumptions, which might reveal other problems. You can go back and forth between the two until you have some useful tests and a descriptive comment. Writing the code to meet those two goals should be pretty easy at that point.

This works even better if you follow the practice of limiting your function/method size. Ideally, your function should not be any longer than it needs to be. If you find yourself having to scroll down an editor to read an entire function, it's probably doing too much and should be split into multiple smaller functions. Personally I try to keep my functions to 10 lines or less, though that's not always possible. Still, keeping a goal for smaller function sizes makes them easier to understand and modify later, and makes writing both tests and comments easier by having a narrower scope.

Many developers will still shun comments in their code, wanting to produce something quickly and get it to compile and run. In the end though, the API's will not be used very much because they're not documented. Also, the code will be more difficult to maintain, not only by other developers, but by the original dev as well. Since most of your time coding will be in maintenance mode fixing bugs and adding features, it's stupid not to add useful comments to your code. By forgoing it you will slow down not only other developers that have to work on your code later (and they'll hate you for it), but also yourself when you realize you have no idea what you were thinking when you wrote that piece of obscure code.

Writing comments before you write your code is a way to not only help you make sure you actually write comments, but also a way to brainstorm design ideas. Comments can be helpful to the development process, and not just a necessary evil that slows down your coding.

Write comments. The world's codebases suck enough as it is, raise the quality a bit!

comments powered by Disqus