Describe Concepts in Comments
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
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
Exactly man, not what is it doing, but WHY it exists and what is the difference between … is important. Cheers
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.
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.
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!
There is certainly a lot to find out about this subject.
I really like all the points you’ve made.
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
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!
Hi there to every one, it’s actually a pleasant
for me to pay a quick visit this web page,
it contains precious Information.
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.
I visited multiple blogs except tthe audio quality for audcio songs existing att this ite is
actually wonderful.
Have you ever considered writing an e-book or guest authoring on other sites?
I have a blog based on the same topics you discuss and would love to have
you share some stories/information. I know my visitors would appreciate your work.
If you’re even remotely interested, feel free to shoot me an email.