This chapter is from the book
This chapter is from the book
This chapter is from the book
"NO COMMENT"
There are valid reasons to write comments. We'll talk about these later. However, as we discussed in Chapter 2, most comments are not written for valid reasons. Fowler's Refactoring[16] calls comments "deodorant". . . they are there to try to hide the bad smell of the code. The code is unclear, the code is poorly written, names are badly chosen, the logic is obtuse, etc. Comments were added to try to explain what the code does. The code should have been, and should be, refactored to make the comments unnecessary.
Don't get me wrong. I'm not saying "Don't write documentation." Nobody really doing XP will say that. Sometimes it is important to the customer to have specific documentation written. Also, I'm not saying "Never write comments." What I am saying is "Never write unnecessary comments." Most comments are unnecessary if the code is written so that the intent is clear. If and when we do write comments, we need to make sure they communicate why and not how.
Valid Comments
As I mentioned above, there are several valid reasons for us to write comments.
-
Incomplete code This type of comment serves as a note to what we were in the midst of working on, or how we see the code evolving. There generally is not much need for this type of comment, since tasks should be no larger than what can be accomplished in a single day. If you find that you do need to make such a note, choose a standard tag for it so you can quickly search for loose ends. And stay away from generic not done yet comments. I'd suggest something like:
// TODO: The tree should be balanced after doing the insertion.
A valid use for this type of comment might be to note code that could benefit from being refactored. Maybe we saw the need to refactor but didn't have time to do it. Make a note so that someone will spot it and do the refactoring when there is time. It might be prudent to use standard wording for these "refactoring To Do" comments so that a global search can be performed as a rough code-debt metric. I suggest something similar to the following:
// CODE DEBT: the looping structure is a bit convoluted, could use // some method extraction.
-
Refactoring doesn't make it clear enough This isn't really a valid comment, rather it is more like the previous type. . . it's an IOU. If refactoring doesn't clean up the code, either someone else should try their hand at it, or (more likely) the code in question should be scrapped and rewritten.
// NEEDS WORK: I tried extract method, but it's still awkward. // Maybe refactoring to a Strategy would clean it up?
-
Use of an unusual algorithm If we use an uncommon algorithm for some reason, we should make a note of it with a comment. Point the reader to where they can learn more. Don't try to document the algorithm in a huge comment. Just note what algorithm it is, why it was used, and where to find more information.
// I used an AVL Tree algorithm here to keep the tree balanced.
-
Use of a published algorithm If we use an algorithm that is published somewhere, we should add a comment saying where and giving credit to the author. This type of comment is often used with the previous type.
// This AVL alorithm was based on Brad Appleton's implementation at // http://www.enteract.com/~bradapp/ftp/src/libs/C++/AvlTrees.html
-
Performance tuning This is important. If we tune for performance, we should add a comment explaining it. At the very least we need to add a note saying that the method in question has been tuned. If we tune without adding such a note we may find that someone later refactors to make the code clearer, undoing the optimization in the process. Keep in mind that we generally shouldn't be performance tuning until late in the project, once performance has been measured and actual bottlenecks have been found.
// A circular queue is used here for performance reasons: to avoid // having to move elements around.
-
Class comment This is the one case that is often useful, in spite of the general disapproval of comments. Not much is required. A simple note at the beginning of the class briefly explaining why the class exists and what it is used for will suffice. Avoid writing a how to use this class tutorial. That's one of the things the tests are for.
/** * This class represents a single movie title. It is responsible for * maintaining its own ratings, reviews, etc. */
A final note related to comments. Programmers often sign their work by including a comment in the file header noting who wrote it. That's fine; credit where credit is due and all that, except:
-
If we are practicing XP, specifically collective code ownership, everyone will likely work on that code. It is owned by the team.
-
A record of who worked on each file will be maintained by the source code control system (SCCS). It is redundant to include the information in the file itself as well. Another comment on this: Please don't include an expandable change log in the file (e.g., $Log$ in CVS). This clutters the code, makes the files larger, and duplicates information that is easy to extract from the SCCS.