No Comment!

Comments - a contentious subject

Every developer has horror stories of the monster codebase without comments, or worse yet, the one with misleading comments.

And last July I saw this - Jeff Atwood advocating coding without comments.  When I see these sorts of articles, I wonder how many multi-developer. multi-process systems the authors have worked on.  While I agree that it's hard to work on code with bad comments, if the code has seen several developers, the comments may be all that exists to explain why things are being done.

Jeff's example is relatively trite - code that implements math functions is almost by definition clear in intent.  If you have a function that implements business logic for a niche industry that will not have a clear meaning to a new developer, or a seasoned one that has been away from the code.  And that's the reason comments are necessary - no matter how good the other documentation may be, the developers will be in the code first, so that's where you need to have the most info useful to programmers.

So when you are coding, add comments that explain the logic behind the code.  Most of it might be doable with correctly-named function names, and variables, but some things are not so easily explained and need a paragraph or two to get that across.

Not this:

a++; // increment a

But this:

a++;  // the hardware uses 1-based numbering

---

Technorati Tags --
Software, SoftwareDevelopment, Computers, Programming
HTTP