To Comment or not to Comment

On slashdot the question was asked what developers think about comments. There are two dominant perspectives: 1. Code without comments becomes incomprehensible over time and 2. code should be self-explanatory without comments.

if you can’t fit the documentation into your method (and variable names), that method is likely too long and complicated.

This is foolish arrogance. In my thirty years in this profession I have worked with many people who thought their code was ‘self documenting’; all of them were wrong, and faced with their own code two years later I doubt any of them could immediately follow it. I’ve only ever worked with one software engineer who, in my opinion, documented enough; I strive to match his standards in my own code but I know I don’t always succeed.

I think this is the wrong way to argue about comments, because comments rot over time — similar to code without tests.

But there are no compiler checks or tests that verify, if a comment fits the code it documents. Over time, the comment rots and instead of helping to understand the code, the comment becomes misleading. This is far worse than code without comments.

There is no general silver bullet to this problem. But one thing is perfectly clear: The code is the truth. It seems sensible to follow clean coding principles, use test driven development, and peer reviews.