Agile FAQs
  About   Slides   Home  

Managed Chaos
Naresh Jain's Random Thoughts on Software Development and Adventure Sports
RSS Feed
Recent Thoughts
Recent Comments

When Should We Encourage Developers to Write Comments?

Many people will argue that there is more badly written code than good code. And its important to write comments to avoid these situations. Therefore we should encourage (force) people to write comments.

IMHO they are absolutely right that today many project suffer from poorly written code without any (good) comments. However every team I know, that suffers from this problem, has always been told (forced) to write comments. In spite of the emphasis on writing comments it has not really helped them.

I usually ask:

By asking developers to write comments are we really addressing the root of the problem?

.i.e. developers don’t invest quality time to write self-documenting code; code that clearly communicates its intent and does not require the deodorant of comments.

May be its time to try something different?

I have seen this myself many times, when we emphasize & educate the team on how to write clean code and ask them to stop wasting time writing comments, the code starts to communicate lot better. Its lot more maintainable. Also we have found that writing automated tests is a great way to document your intent as well.

This is how I would explain the concept Comments Smell to a team:

Writing comments that explain “how” or “what” the code does, what it does, is evil IMHO. Comments (esp. about what and how) is a clear failure to express the intent in code. Comment is a deodorant to hide that failure (smell).

  • If developers don’t invest time to write clear code, what is the guarantee that they will write clear comments?
  • Is doing a mediocre job at both (comments and code) better than doing a great job at just Code?
  • Will it actually be more productive to do both or just one?

Remember the biggest problem with comments it that they fall out-of-sync with code very soon. So its not just about the extra investment to write good comments, but also the investment to maintain them.

One has to think hard to write code that expresses intent rather than write some sloppy code with poor abstractions and get away (washing their hands off) by writing comments. Developers have to take responsibility for writing code that others can easily understand.

Having said that, there are times when “the why” (why we are doing something in the code, a particular way) is not apparent by just looking at the code. So if we don’t find a suitable way to communicate “the why” through code, comment is the fall back option.

Note that comments are a fall back option in “the why” case rather than a default option.

  • Yogesh Sood

     I agree with writing clear code there is no two ways about it. However I think comment need not to always describe code sometime they are handy to understand the business case related to the code. May be I understand the code as it is written clearly but i don’t understand business case that  why this code piece is needed here. In large code bases I find it easy to have some comments related to business case. On other aspects mentioned in this article like automated tests i agree.

    • Yogesh, The question I would ask is, can we use Acceptance Test to define
      the business case? Does it really belong inside the code as comment?

      • Yogesh Sood

        Hello Naresh,

        We can and should use Acceptance Test , however point I’m making is that sometime when you reading existing code and trying to make sense out of it some handy comment related to its usage really helps, and i think nowadays code is not only java code with Spring being used most of the places xml config is significant part of code.

        For example the values mentioned below is being passed to a Spring bean , in this case you cannot rename these values to be meaningful as they are being generated from some other system and denotes prefix/sufix of the file a program will read later. point here is that If those comments are missing when Im reading code I have to struggle to figure out what APTEO means eventually I would find it without a comment here but it is desirable to have them where they make sense.



    Licensed under
Creative Commons License