Comment rot

There’s an interesting discussion going on on the ACCU’s mailing list at present. It’s about the value of comments in code. This is one of those topics that comes around every so often and this time I decided to dive in with some controversial suggestions.

The discussion started with someone saying how they’ve just had a code review where the reviewer insisted on adding the following comment:

// Checks the name length

void CheckNameLength()

This moved into a discussion about block comments in headers and my position was that as soon as any of them start to get out of date the value of any of them starts to diminish. Comments rot quicker than code and most of the code that I’ve had to look at has had poor or out of date block comments. As soon as I find comments that aren’t telling the truth I start distrusting all of them and at that point they become noise and don’t offer me any value, so rip em out. I guess my time spent with The Refactoring Project may have affected my view of such comments…

The proponents of block comments came back with arguments such as they’re fine because they’re checked along with the code during the code review stage and so don’t slip out of sync. I wish I could work with clients where this was the case. It would be nice to find a client that actually did code reviews…

They also argued that auto generating documents from the comments and then reviewing the docs to make sure they’re useful tends to help with the quality of the code comments - I agree here, much as I hate auto generated documentation a few years ago I produced a sysytem for the client that I’m doing the refactoring for where they used Doxygen for document generation and where someone was actually interested in the output. The system was commented appropriately and the documentation was quite useful as a reference. The system in question hasn’t needed to be changed since it was completed so the comments haven’t had the opportunity to rot and the documentation is still useful.

That brings me to the main point of their argument. Block comments like this are good and worthwhile in library code that doesn’t change quickly. I guess I agree, but I’ve found that these kind of worthwhile comments tend to only come into existence as the code base matures. Even then I think they should only be used where they actually add value…

I’d still, personally, prefer a decent document written in a word processor to an auto generated document based on comments… These documents can have diagrams and can be written to explain the why of the code and give an insight into the design trade offs that took place during development.