Over on the Great Wide Open blog by Esther Schindler, is an article entitled “If the comments are ugly, the code is ugly.” She was inspired by this quote:

Good programs do not contain spelling errors or have grammatical mistakes. I think this is probably a result of fractal attention to detail; in great programs things are correct at all levels, down to the periods at the ends of sentences in comments.

“Aw, c’mon! You’re kidding!” You might think that nit-picking like this is beneath you, whereupon I will start pointing out errors in your code. It was embarrassing the first couple times this happened to me.

— from the article “30 Years of C” on the DadHacker.com blog.

In my personal experience, I have have seen a common correlation between poor comments and poor code. I won’t take an extreme position as DadHacker or Esther but I have noticed that well thought out comments usually appear with well thought out code. Clear and concise comments with clear and concise code. Certainly there have been exceptions especially with developers whose first language is not English.  And the reverse has usually been true. Sloppy or non-existent comments with sloppy code.

Are certain languages more prone? Maybe, maybe not. However some years ago I was part of an organization that coded in Perl 3 for almost everything. We had some real gurus (”mad skillz”) on the team. One whom I hired directly that used to work with Larry Wall (inventor of Perl). Unfortunately these wizards, while some of the most expert Perl 3 developers (if the most) in Silicon Valley there were mostly very poor at documentation. Which given the nature of Perl 3 (the ability to combine multiple lines of code into a single string), documentation is even more important than with a more visually structured language like C++. I could and still do really appreciate the wizardry and elegance of writing such few lines of Perl code. It’s certainly beyond my ability. However in the end, if code cannot be maintained or understood by those that come after you then in my opinion it has failed. Not to mention that object-oriented Perl 3 development skills was (and probably skill is) hard to come by. But that rant is for another day.

So what’s your experience? Is there a correlation between good code and good documentation? How much documentation is “barely sufficient”? Have any Perl 3 stories to share?