Thursday, June 6, 2013

State of the Art - Don't Comment Your Code

I was listening to a Java Posse podcast this morning, and the hosts were discussing the pros and cons of putting comments in your code.   I consider myself a software craftsman, and a big part of that involves writing readable code.  I have done it often enough to know that good code really doesn't need comments, and by that I mean any non-Javadoc comments.  (And only your API code should have those.)

The fact that the Java Posse guys seemed unaware of this as a practice surprised me, so I did a little digging with the expectation that this "obviously beneficial" practice was being used by most, but not all developers.  I was surprised to find a number of fools who were dismissive of the idea, in addition to a number of obviously intelligent people who agreed with me.  Apparently this is not yet a mainstream concept.

I have worked at a lot of places, and the best, most maintainable, easiest-to-change code I have ever seen was all written at my current workplace where "no comments!" is the norm.  Really top-notch programmers can certainly still create excellent software with large methods, confusing method and variable names, and other code smells.  Mere mortals will struggle to change such code, though.

So why, if this is so obviously beneficial, is it not standard practice across the board to avoid comments whenever possible?  I have a few ideas, based on my experience in different software shops:

  • Some codebases are changed very slowly or simply have the expectation that any change will be time-consuming and expensive.  Such code is probably internal-only.  In this case it would be less obvious that the code is hard to change.
  • Many programmers don't consider themselves professionals, and don't try to keep their skills up-to-date with constant self-education and practice.
  • I'm wrong.
While the third bullet point has happened before, I don't think so in this case.  I suspect rather strongly that the second bullet is the most likely one.  It's easy to let your skills and knowledge go stale, so that's what most people do.

If that describes you, beware!  You're not likely to remain employed in this brave new world if you're not competitive.