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

10 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 [...]

  5. Very good site you have here but I was wondering if you knew of any discussion boards that cover the
    same topics discussed in this article? I’d really love to be a part of community where I can get feedback from
    other knowledgeable people that share the same interest.

    If you have any suggestions, please let me know.
    Many thanks!

  6. There is certainly a lot to find out about this subject.
    I really like all the points you’ve made.

  7. Tentez nos solutions pour vos envois b2c de MMS.
    Utile pour le particulier comme pour l’entreprise, le service vous permet depuis votre bureau de rédiger vos messages à destination de tous vos clients.

    Faite pour gérer de très nomreux envois, notre système d’envoi est d’une fiabilité sans
    égale pour effectuer vos expeditions en masse.
    Doté d’une puissante interface de mailing, notre service est le top des
    API d’expédition de MMS et de MMS.
    Vous pouvez mettre au point facilement vos campagnes à destination de centaines dee cliens.

    Heree is my page :: Envoi de MMS pro

  8. Spot on with this write-up, I actually believe this
    amazing site needs a lot more attention. I’ll probably
    be back again to see more, thanks for the advice!

  9. Hi there to every one, it’s actually a pleasant
    for me to pay a quick visit this web page,
    it contains precious Information.

  10. Simply want to say your article is as astounding.
    The clearness for your submit is simply spectacular and that i
    can think you’re a professional on this subject. Well together with your permission let me to snatch your feed to keep up to date with impending post.
    Thanks a million and please keep up the enjoyable work.

Leave a Reply