Describe Concepts in Comments

August 9, 2011

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
If you find the content interesting, you can subscribe and get updates


4 Responses to “Describe Concepts in Comments”

  1. Exactly man, not what is it doing, but WHY it exists and what is the difference between … is important. Cheers

  2. It’s common knowledge that commenting your code is a must.

    Unfortunately it’s not universally agreed that commenting your code is a good thing. I have had the misfortune to work with Agile and Xtreme programming types that insist that comments, any comments, in your code indicate that your code is unreadable.

  3. Now, it’s true that code should be self-documenting. That is, there is no need to write “we increment this”, “we swap these elements”, “saving the object” or “sending over the wire”. But the general concepts in more complex projects can’t be communicated directly through the class name and its methods.

  4. [...] the core classes and any non-trivial use-case within a method is part of coding best practices, and good programmers do that. It makes understanding the code much easier for other people, and together with writing [...]

Leave a Reply