I've often heard developers scoff at the very idea of adding comments to their code. Indeed, I've even worked on projects with fellow programmers where their submissions lack even a single comment.
When challenged on this, the argument I receive time and time again is one of 'code should be self documenting'. Yes. But no.
You are correct, code should be self documenting. But you've missed the original point. We are talking about comments, and comments are not the same as self documented code.
Let's examine an example to illustrate the point:
var a = 3.14159265359f * radius * radius;
Is far more obfuscated than:
const float PI = 3.14159265359f;
var areaOfCircle = PI * radius * radius;
I hope you'll agree this is a nice succinct example of self documenting code. Whereby both the constant and the variable name serve to communicate intent locally without having to read further down to understand how a gets used or where radius came from.
So when to prefer comments over self documentation?
Easy. If the code would become unnecessarily complex or
architecturally compromised simply to
satisfy something which a comment could solve with zero impact.
If you can refactor code to make some specific design decision bubble to the surface for easy comprehension
then well done; you've achieved self documenting code (just be careful you're not
eating too much into development time). But if you're twisting and breaking your
well crafted API simply to let people know that you had to 'do it this way'
because there is a bug in some library you depend on which only occurs on one
platform if it happens to be a leap year, then I'm afraid you've dropped the
public void FindPathUsingModifiedAStarUsingMapsWithNodeGraph(int x, int y, Grid map)
//based on A* - http://www.policyalmanac.org/games/aStarTutorial.htm
//map: expects node data to speed up graph traversal
public void FindPath(int x, int y, Grid map)
The signature is far more sensible and the comments actually communicate more information. (I know this is simplistic but I hope the reader can see the key point here.)
If you're wondering what I consider potential candidates for comments; I submit:
- Optimisations (speed, memory etc.)
- Minor bug fixes which don't impact the public interface.
- Questions or points of consideration. ('May need to come back to this once we have more time')
- Justifications. ('This may look whack but I had to do it this way because...')
- Elaborations. When the self documentation within the code just isn't enough.
- Anything temporary that shouldn't end up in the release build (TODO's)
- Thinking about it there are actually tons of reasons!
But comments are evil
I know, comments have the fair share of problems. They're instantly out of date, they add cruft to the code that only humans understand, high level
languages are designed to be understood by both machines and humans so what's the need? These are all wholly valid points but everything comes with pro's and con's. No one is advocating a 1:1 ratio between LoC's and comments. That would be
ludicrous. The advice here as with most things in our field is to apply common sense and justify everything on a case by case basis. If it needs a comment stick it in. If you can explain it in the method signature prefer that.
My fear is that developers who don't agree with this or have never considered these points have probably never worked on projects which require them. Which is fine. Just stop saying never.