It’s common knowledge that commenting your code is a must. But that’s where the wrong interpretations come. “// incrementing i” above “i++” is one extreme example of useless comments, but what can be often observed is “shallow commenting” – i.e. comments describing what exactly is done, but not why. In other words programmers may forget to document the concepts and ideas behind the code.

For example, imagine you see ClientDocumentIndexer and DocumentIndexer. What’s the difference? The code may have comments explaning what happens when sending the documents to the search engine, but there is nothing about the difference between the two. Same goes for things like DownloadRecord and DownloadLog. And for millions of examples throughout thousands of codebases. The comments in these classes fail to communicate their business purpose. Then there is the FooListenerBuilderFactory – yes, I know all these patterns, but it still doesn’t make sense without an explanation why each of them is required.

Sometimes there is sufficient explanation about these concepts in some intranet document. There’s just no link between the code and the description. Adding a link will most likely be sufficient for the reader to understand what’s the purpose of a given class or method.

What if there is no spec/document? Then you’d have to write that “document” in the code. Don’t be verbose – just outline the reason for the class existence, and how it fits into the program flow. Each piece of code should make sense to someone that is not familiar with all the business requirements.

Sounding obvious? Well, if it was, you wouldn’t be seeing code that is hard to understand out of context.

To summarize:

• document the concepts and ideas of a class, not (just) how it functions internally
• if relevant, explain the reason for a class existence and how it differs from similar classes
• document the context of a class – how it fits into the program flow
• link requirements documents, if such exist

From http://techblog.bozho.net/?p=463