Skip to main content

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.
Post a Comment

Popular posts from this blog

Agile Performance Management: Why Performance Reviews Suck

Many thanks to Mary Poppendieck, who wrote about this topic in 2004, and proposed a comprehensive solution.  She is the inspiration for much of my thinking on this subject.  She is also a better writer than I am a cartoonist.


Performance reviews suck.  I don't know of anyone who goes into their appraisal without some trepidation.  Your boss is guaranteed spring some surprise criticism on you that is ill-informed or misses the point as you see it.  It's a real challenge not to get defensive about that.

The only thing that makes your own performance review suck less is having to give them.  As a manager, I have dished out quite a few, and some of them went pretty badly.  (To the people at my first management job: Thanks for helping me learn how to get better at them.  Your sacrifice was not in vain.)  Since then, receiving one isn't nearly as gut-wrenching, if only because I try to make it easier for the guy on the other side of the desk.  I've been there, and I know how …

Do. Not. Optimize.

You've probably heard this quote before:
Premature optimization is the root of all evil.
 - Tony Hoare
Speculative optimization is always wasted time.  In the absence of an actual performance problem, you're just burning time that could be better spent on refactoring your code to make it clearer.  This is exacerbated because performance-optimized code is usually harder to read than code which hasn't received such treatment.

Here is what you're doing when you optimize:
Adding code that now must be maintained.Obfuscating the existing code.Spending time writing code that doesn't add value. But what's that you say?  You have the experience and know-how to decide when optimization is needed?  Maybe, but probably not.   The people at Sun and Oracle may or may not be smarter than  you or me, but they certainly know more about optimizing Java bytecode than we do.

For example, some people think that having a large number of classes is slower than the alternative.  This …

Showing Off: How to Do a User Demo

Rather than repeating what has been said elsewhere, here is a nice short post on agile-for-all that covers the basics.

Here are a few things for my own future reference and teams that I'm working with...

Try to keep each demo to 5 minutes or less.   If it's longer than that, it's possible that you should be demoing more than one story.  More likely, you're just being too wordy.

TALK LOUDLY.   No, louder than that.  Louder.  Do you feel like you're yelling?  OK, that's about right.  You need to put your voice in public-address mode for 5 minutes.

Focus on why your audience should care about the story  This is particularly important for back-end work.  For example: Your story generates a feed of XML that will be consumed by another application. Show the output, and point to a couple of salient features in it.  Then be done.

The important part of the above is "show the output."  Showing the end users how to interact with your service is a separate sit-d…