Inline Comments in the Code is a Smell, but Document the Why
Is writing inline comments always bad? Are comments really evil? I keep getting these questions over and over again.
Often you see code like this:
// If the item is taxable, get the taxed amount using tax calculator if( objItem.bTaxable ) { objItem.fTax = objCalculator.TaxForLocal(objItem.fItemRate); } // Additional tax is applicable if the item is an imported one if( objItem.bImported ) { objItem.fTax += objCalculator.TaxForImported(objItem.fItemRate); } // Add tax to item rate objItem.fTaxedRate = objItem.fItemRate + objItem.fTax; // Return the final amount double fFinalAmount = objItem.fTaxedRate * objItem.nNumberOfItems; return fFinalAmount; |
What is the real value of these comments?
When I see stuff like this, I usually tell people
When I was learning programming, I was thought that great programmers write great comments. These days I tell people lousy programmer write comments.
Immediately people who write inline-comments get defensive. And that’s completely understandably. I don’t think we’ve really explained our rationale for making such a ridiculous statement. So let me step back and explain the rationale.
Folks in the extreme-programming community will tell you:
Comments are often used as deodorant. Comments represent a failure to express an idea in the code. Try to make your code self-documenting or intention-revealing. When you feel like writing a comment, first try to refactor so that the comment becomes superfluous.
Most people will also tell you, that the biggest problem with comments is that they soon become outdated. The original intent of the person writing the comment was to help a developer who comes later to understand the code better. But unfortunately over a period of time, the comments get outdated and it adds more to the confusion. Speaking to many programmer, they simply delete or ignore the comments because they find them ambiguous. Even though the person who wrote the comments wrote them with a good intension, one needs to ask if it really solved any problem?
And then they question, why not put the same effort and time to write well-crafted code so that comments are never required? Is it impossible to do so?
While this argument is a good one, I find it hard to connivence people just based on this argument.
I’ve found the following approach work really well for me. First let’s understand why programmers write comments. Based on my experience, programmer write in-line comments for 3 different reasons:
- To explain what the code does
- To descrive how the code does what is does
- Why the code is written the way its written
If you think about it, the “what” and “how” of the code should really be expressed by self-documented code. IMHO its simply a failure on part of the programmer if they cannot express the “what” and “how” in the code itself.
However the “why” is little bit more tricky. It’s a reminder, telling us: “Hey, you are doing something complicated and someone else will not understand why. Even if you wrote a comment, they might not necessarily understand it.” At this point I might stop and see if there is a better way to design/model/code this, such that the why becomes obvious via the code. This is certainly more challenging and time consuming than to write a comment and moving on. However this short-term hack might bite me back. Luckily, most often than not, I can find a way to avoid the comment. But there are special cases when I need a comment to explain the why. Let’s see a few examples:
- There is a bug in the underlying framework/library I’m using. Searching on the net, I found the bug report and a workaround. Looking at just the code might not help someone understand the need for the workaround. Generally I would write a small comment saying Workaround with the version number of the framework/library and add the link to the workaround and continue. In future, someone can remove the workaround & delete the comment if the issue is fixed.
- I’m implementing a complex algo and its not common that everyone understands it. I would add a link to the Algo description (rather than duplicating the algo description in the code. DRY principle applies to comments as well.) and continue with my coding.
- And so on…
So think again before you leave a comment 😉
