Comments in Code

Comments in code are like “The Force”; there is a light side and a dark side. Poor comments can be worse than no comments at all. This article attempts to play Yoda, showing you the difference between good and bad commenting in code.

There are engineers who having been told that comments are good assume that more comments are better; they are wrong. Too many comments in code can often be worse than no comments at all. Comments take time and effort to write; adding unnecessary comments represent wasted time. Comments take time and effort from the maintainer to read; those unnecessary comments costing time that should be spent gaining an understanding of the code.

Before writing a code comment remember that comments exist to help future maintainers of the code. If a comment does not serve that purpose it is not needed. The key rule in determining when not to write an inline comment is:

Comments should never explain what the code is doing

The person who reads your code can determine what the code does by looking at the code. If you are writing code in a manner so complex that you feel compelled to write a comment, you should be refactoring your code to be clear and not adding a comment.

Comments that just explain the code are also at risk of diverging from reality. For example, I have seen situations like the one below:

The comment does not describe what the code does. The code is actually multiplying (N+1)*(N+2). The maintainer is now faced with doubt. Is the code correct, or is the comment correct? They are obliged to spend some time looking at old versions of the code to see if it was once accurately reflected by the comment, look at unit tests to verify that the code is working correctly, find the original developer and ask if they recall which is correct, or study the code. Any or all of these activities represent time wasted because of an inaccurate comment that was not needed in the first-place.

Comments should explain why the code does what it does. Comments providing a summary of why a particular approach was used are helpful, they save the reader from having to look for that information from other sources.

The previously stated rule to avoid comments that explain what the code does is not as black and white as I made it seem. There is a qualification that I made; the rule applies to inline code. Comments that explain what code does are useful as headers for a class or function. A brief summary of the purpose of the class or function can help the reader understand more quickly than reading the code. In general, I would avoid listing parameters in these headers, as there is the risk that code and comments can get out of sync. This does require that you have parameter names that make the purpose clear; calling them p1, p2, p3 is not helpful. However, for languages like Ruby where the parameters do not have an explicit type listed, it is helpful to list parameters with their type.

Comments are something which should be considered as part of a code review. Comments that are incorrect or superfluous should be identified in a review as needing to be removed. If anyone asks why a particular piece of code is written the way it is, that implies that a comment be added.

Remember: bad, too many comments are.