Can One Write Too Many Comments?

A friend of mine recently was watching a youtube video where somebody said coders should not comment their code.  My friend blamed this way of thinking on the TDD "fad".  His solution:  javadocs.

I asked my friend if he had read anything by Robert C. Martin and suggested the book "Clean Code".  He said the name was not familiar to him.  He said he doesn't read a lot of books but gets most of his ideas from the internet.  One exception he noted was a book called 21st Century C, which I am not familiar with.

Anyway, this argument about comments has been going on for as long as people have been promoting TDD (Test Driven Development) philosophy, and perhaps even longer.  When Martin Fowler wrote his book on Refactoring in 1999, one of the first books that mentioned JUnit, he categorized comments as a "code smell".  To be fair to Fowler, he said comments are a "good smell", but that they are often used as "deodorant" to to cover up for bad code.  So, too much comments may be a sign of problems.  This idea was just one part of the "extreme programming" mindset, which represented a paradigm shift which was difficult to fully accept but brought many advantages for developers.

Lean principles and my own experience tell me that too much effort placed on activities that do not directly impact the end product, such as comments (and documentation in general) can be a waste of time.  (It suddenly struck me as a bit ironic that I'm making a statement like this while writing a blog post which itself may not be the most productive activity, but whether anybody else reads this or not at least I can justify that this is an exercise useful for helping me organize my own thoughts and think through my own opinions.  Perhaps the time spent on documentation is kind of like that.)

Years ago I had a professor that insisted every single line of code should have a comment.  I have never met anybody else that wouldn't agree with me that this is a wasteful extreme.  I also have worked on projects where every function and/or file had to have a header comment, every variable had to have a comment describing what it was, and/or every change to a file had to be explained in a comment.  I even worked on one project where the rule was to never delete code, you always just commented it out.  People running these project obviously felt their rules were important, but I did not agree.

I have also worked on waterfall projects where business analysts took so long to determine requirements that there was not enough time left for actual coding the project.  I would rather produce something useable within budget constraints than try to create something perfect that never gets finished.  As they say, "perfect is the enemy of good."

In Clean Code, Martin acknowledges that Javadocs are good for describing a public API, but goes on to say that most other comments are bad and devotes several pages to support this assertion.  Has Martin gone too far?

Back to my discussion with my friend, we agreed that extremes are generally not good.  In fact, I think everybody, including managers who sign off on software projects, intuitively know that, and so I think the naming of "extreme programming" is sort of unfortunate.  XP practitioners labeled their own ideas as out of the norm, perhaps even unproven or risky.  I think they were going for the "coolness" factor calling to mind "extreme sports".  Perhaps they would not have gotten anybody's attention without the cool name, but in the long run "agile" and "scrum" sound more positive and safe.

I think comments can be helpful when they relate why a developer implemented code in a certain way.  I often put in TODO or FIXME comments in code when I know there is probably a better way to do something, but I just do not have time to explore it further.  Sometimes when I copy code from examples I find on the internet I like to put a comment giving credit to the original author and/or a link to the web site where the code came from for future reference.

However, I do not believe in hard and fast rules for such things.  I understand why managers create such rules.  I have been in management roles myself, so I know how much pressure there is to succeed and how hard it is to ensure some level of quality while getting things done quickly and minimizing risk.  But from a programmer's perspective what we run up against is that each new project has a new set of arbitrary rules.  One project might implement Uncle Bob's rule of almost never writing comments, while another project goes to the other extreme.

As programmers we just want to do a good job, but we don't want a stifling set of arbitrary rules.  We value creativity and individuality.  The agile manifesto states this quite clearly.  So, some things should be a topic for discussion amongst programmers and not something that should be imposed from the top of an organization or even by tyranny of the majority of programmers in a team.  I would argue this is one of those cases.