Step 2 - Climbing the ladder...
# Tuesday, November 13, 2012

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 ball.

Consider:

        public void FindPathUsingModifiedAStarUsingMapsWithNodeGraph(int x, int y, Grid map)
        {
            ...
        }
        

Versus:

        //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.

Further reading

Recent posts

Tuesday, November 13, 2012 1:18:34 PM (GMT Standard Time, UTC+00:00)  #    Comments [0]

Posted under: Programming by

My latest artwork
View my entire gallery.
Archive
<November 2012>
SunMonTueWedThuFriSat
28293031123
45678910
11121314151617
18192021222324
2526272829301
2345678
About the author/Disclaimer

Disclaimer
The opinions expressed herein are the personal opinions of Adam Naylor and do not represent my current or previous employer's view in any way.

© Copyright 2014
Adam Naylor
Statistics
Total Posts: 55
This Year: 0
This Month: 0
This Week: 0
Comments: 8
Creative Commons Licence
© 2014, Adam Naylor