The following describes some of the various different types of bad code comments and anti-patterns as well as what we can do to improve them.
Rotting comments
Rotting comments are ones that have become out of date and are misleading. They make no sense and bear no relation to the code they are placed near. This is probably because the comment the code was meant for has been modified/deleted/moved/etc. and the comment was simply left behind untouched. Unfortunately programmers tend to maintain comments a lot less than code.
A rotting comment is especially bad because it can cause a great deal of confusion to the reader. In all such cases “the code is king” and you should trust the code over the comment. After all the code is being executed and the comment is not.
In this situation the comment has lost it’s value so there is not much else you can do to improve the situation except delete the comment.
Parrot comments
Beware comments that parrot the code. These types of comments are completely redundant. Consider the following code and comment:
int i = 1; // Initialize integer and set it to 1
The person reading the code (and your comment) is a programmer, otherwise they wouldn’t be reading it in the first place. This means they don’t need comments to teach them how to read code.
I personally have a strong suspicion that coders that follow this antipattern (and aren’t literally learning to code) have learned it from examples in programming books, blogs etc. and so assume it is a good practice. The reason the author of the book/blog/etc. wrote comments like this was to help teach the reader how to code. However, when you are writing production code you don’t need to teach everyone else.
My recommendation if you see a parrot style comments is to delete the comment and if required refactor the code and make it more readable.
Commented out code
Avoid commenting out code and committing it to your source control system. When another developer sees your commented out code it can lead to confusion. Commented out code also tends to build up as developers are often scared to delete it thinking it must be important or related to another team member’s work.
Simply delete the line of code instead of commenting it out. Your repository has a history and getting the deleted line back should not be difficult if you need it again.
Closing brace comments
Consider the following code:
if (companyId = 1)
{
// lots of code ... foreach (customer in customers)
{
...
} // end foreach} // end if
Most closing brace comments clutters the code and makes it harder to read.
In fact most IDEs can already get round this problem by highlighting brace pairs (for example in Visual Studio if you place the cursor on the beginning brace the end brace is highlighted).
Also, ask yourself why you need to visually see the beginning and end of the brace delimited block of code in the first place. If there is so much code between the beginning and end brace then it is probably a smell that the code should be refactored (extract method/function, extract class etc.) rather than commented.
Comments on every single method/function definition
Not every single method/function you write needs to be commented. In fact the vast majority probably don’t. If you do feel the need to write a comment for a method/function first think how you could refactor to better reflect what it does. Things to look at include:
- Improving the name of the method/function
- Improving the name of any parameters
- The number of parameters. Using more than two or three parameters can quickly lead to complex method definitions that are hard to understand.
- The order of the parameters in the method/function definition. Would changing their order make more logical sense?
Another consideration is the scope of the method. Often the more private the method the more unlikely you need any comments in it’s definition. Where as a public method in a package that is going to be consumed by other applications would often be a better candidate for comments.
Journal comments
Some comments may have the date time in the comment, details of the author of the comment or even an issue number relating to a bug or requirement that the subsequent code fixes/implements.
Just like with the “commented out code” anti-pattern (see above) with the advent of good source control these kinds of comments are usually redundant and can be removed. Any issue or requirement information can instead be included in the source control commit message and the author of a change will also be tracked.
Copyright/license comments
Don’t litter every code file with long copyright/license information. Use a single license file and place it at the root of your code base (then if you have to, refer to the license file from your code file). This practice has very much become an unofficial standard when using Git repositories.
Mumbling comments
A mumbling comment is one where the developer is essentially talking to themselves. For example:
// I think this is faster than the previous implementation. Not sure, still have to test. Waiting for the QA to come back from leave.
Unfortunately these kinds of comments usually have little value. If possible extract any value from the comment into a new concise comment (or even better refactor the code) and delete the original comment.
Mandated comments
Some companies/organisations mandate comments for certain parts of the code. For example there might be a rule that every method/function must be fully commented with a description of the function, each of its parameters and its return value. Mandating arbitrary rules such as this will often lead to developers writing stupid (usually redundant) comments.
Conclusion
Comments come at a cost. They take time to write, take time to read and take time to maintain.
Comment only what the code cannot say. If you can refactor the code to say the same thing then that is always more advantageous than writing a comment. Bad code should be “cleaned” not commented.
A common saying amongst developers is that comments should describe the “why” and not the “what”. This is because the “what” can usually be written in code. If you encounter a “what” style comment the solution is usually to refactor the code and remove the comment.
Other situations where a comment may seem completely relevant is in anticipating likely questions from other developers or advertising likely pitfalls, surprises or how something might be misused.
Comments in of themselves are not bad (they are also not “pure good”). They are instead another tool in the developer toolbox and like all tools they should be used at the appropriate time and in the appropriate place. Before writing a comment think can I express myself better in the code? Can this information be better recorded elsewhere (such as source control)? And ultimately will the comment add real value?
