Code commenting - the myth

[haxhaxhax]

I have lately been embroiled in a debate about the importance of commenting in code. While I don’t yet believe that comments are completely unnecessary, I tend to think that they are largely unnecessary. Almost two years ago, I wrote ‘Software development without maps’ in which I extolled the virtues of ‘documentation’. While it can be easy to

Comments

[alaryn]

Urgh, I tried to reply on your other blog, but it seemed to get flagged as delicious spiced ham :P

[haxhaxhax]

Really? I can't find the comment anywhere..

p.s. spiced ham is delicious

Re: /** epic post is epic **/

[alaryn]

What I wanted to explain in my other post on the other blog with the same epic post... is that while I'm not a programmer, I've certainly heard how useful comments are for understanding code that's got a very hacky bugfix.

Also, from a Designer's perspective, notes are handy for explaining why you did something a certain way, and thus why it shouldn't be revised :) (I didn't put this in the other reply)

Re: /** epic post is epic **/

[haxhaxhax]

It's certainly understandable to have comments to explain hacky and convoluted bugfixes. However, one must take care to not let hacky bugfixes become the norm, rather than the exception - an accumulation of hacky bugfixes is simply a sign of a poor maintenance process.

Ideally, given a growing collection of hacky bugfixes, it's in the best interests of everyone for particular subsystems to be refactored or re-engineered more cleanly. While clean architectures may take time and skill to build and maintain properly, the ongoing maintenance cost is closer to being linear, compared to an exponentially increasing cost of maintenance on a pile of hacky and incoherent bugfixes.

Re: /** epic post is epic **/

[haxhaxhax]

The impact of 'laziness and incompetence' is greater for poorly designed code, compared to the impact of the existence of comments.