Sometimes I’ll ask my students if they think that commenting code is a good thing or a bad thing. Some people laugh. “Of course it’s a good thing,” they often say. But is this universally true?
When I worked at IBM back in the ‘80s we had a programming standard that said every line of code should be commented. To me that was absurd. If I have a line of code that says…
x++;
…then I do not need a comment that says…
/* I am incrementing x here */
I can assume my reader understands the basics of the programming language.
Commenting every line of code often got in our way. We would update the code but sometimes forget to update the comment and so the comments would be out of sync with the code. A comment that lies is definitely worse than no comment at all.
Let’s distinguish between “what comments” and “why comments”. “What comments” describes what we are trying to accomplish and is often best left omitted. Martin Fowler refers to “what comments” as a “code smell” indicating that something may be wrong. Perhaps the programmer added the comment because she felt the code wasn’t clear enough on its own.
It should be clear what a piece of software does by naming the classes, methods and variables involved so they express the intent of what you’re trying to accomplish. Using intention revealing names significantly reduces the need for “what comments” in code.
Martin Fowler has a great test to see if his code is clear. He will write code using intention revealing names and straightforward logic but without comments and then give it to his wife to read. Martin Fowler’s wife is not a programmer but if she can get the gist of what’s going on by reading the names and seeing the basic layout he considers the code understandable. If she can’t figure out generally what’s going on in the code he will go back and rewrite it until it is clear.
Often when I am writing a method I will rename it 4, 5, 6 or more times as I am writing it because I am getting clearer about exactly what it does and therefore what it should be called. This helps me spot cohesion issues as well. If I have trouble naming a method it is usually trying to do too much and should be broken out into multiple methods. Naming is one of the most difficult and important part of a developer’s job.
Some “what comments” are valuable. API’s should be documented to express what they do so we know how to use them properly. I find myself writing “what comments” that callout bugs or non-intuitive conventions, which seems to abound in Windows APIs. I might write “You might think that you call this method this way but it only works when you call it that way.” This embeds my learning into the system. But if I can express what I’m doing through naming and the use of straightforward logic then I am not compelled to add comments to my code.
There is another kind of comment that is sometimes call “why comments” that are good to put in our code. These comments express why we are doing something, for example conforming to some federal regulation or using a design pattern or a specific coding convention. These comments help the reader understand why we are taking a certain approach so they better understand the motivation. “Why comments” can be extremely valuable.
Often “why comments” are block comments put at the top of a class or method to help us understand the overall motivation for piece of code or set the convention for handling a particular issue. I like “why comments” because they set a context for why I’m doing something and it is more likely that people who maintain the code in the future will understand and use the conventions I set up.
What about your code? Is it always clear what’s going on or do you have to write comments so the reader will understand? Let me know. Your comments are welcomed.
{2 Comments }
Previous Post: « The Wall
Next Post: Not Like Civil Engineering »
Thank you for the suggestions.
Exactly. The comment that shows what you INTENDED is the comment that you must have. Everything else is Cake-Icing or Crufty-Barnacles.