Commenting Code

Why should I comment code? It’s obvious what it does, right? Worse, over time, the comment “decays”, since updaters never fix the comments, and comments become less and less relevant over time. Sure, a high-level ‘contract’ comment is important, but implementation?

Precisely! Which is why I advocate NOT to comment “live” code, but instead to comment why previous code is now “dead”. I call these ‘scar’ comments: comments that stay behind to explain why old code didn’t work, rather than attempting to explain what’s happening ‘now’.

Sometimes that’s best done with a commented-out previous line of code – but please give an English reason of its now-exclusion as well? The most important reason to leave old ‘scars’ behind is to stop someone from trying that same approach/fix/’solution’ again. If you just leave the new code, and another issue arises, people may be tempted to try old fixes that didn’t work… a well-described ‘scar’ should deter them.

The best thing about this is that a ‘scar’ comment will remain forever – unless the ‘skin’ is completely replaced, and the fundamental raison d’être has gone.