This story was written by Keith Dawson for UBM DeusM’s community Web site Develop in the Cloud, sponsored by AT&T. It is archived here for informational purposes only because the Develop in the Cloud site is no more. This material is Copyright 2012 by UBM DeusM.

About Comments in Code

Thinking about the how, why, and why not of commenting your code.

Discussion has erupted around the Net about code commenting, as it does periodically. Here are some of the subtleties people are bringing up on the subject of comments.

It began with a blog post by Zachary Voase, The problem with comments, that got linked in Hacker News. Soon Slashdot regular theodp put Voase's piece together with a recent post by blogging pioneer Dave Winer, and a Slashdot editor selected it for the front page.

Voase's complaint was that code editors and IDEs let you hide comments, but they don't have a mode that makes the comments pop out while de-emphasizing the code. Winer also commented (apparently without having read Voase's post) on the ability of editors to elide comments, among other topics in the process of code creation and maintenance.

The ensuing Slashdot thread really got the discussion moving -- at this writing it has garnered over 350 comments. Here are a few of the considerations that were raised on the surprisingly subtle subject of code commenting.

When I was learning programming, in the Dark Ages of the computer era, we were taught that comments were necessary in code -- an unalloyed good thing. Many software shops mandated commenting; some even measured programmers' comment output and graded them accordingly. The idea was that you were writing comments to guide the next person who picked up your code. This could even be you, a month from now, by which time you will have forgotten your thought processes while creating the code.

This view of code commenting was explained well by Jeff Atwood a few years back in his post Code tells you how, comments tell you why. Comments provide the metadata that code itself cannot. A Slashdot reader, trout007, expanded on this theme by explaining what some other engineering disciplines do:

I'm a mechanical engineer. Our "code" is models and drawings... But you don't just deliver a set of drawings as a product. You have Analysis Reports, Design Manuals, Operation Manuals, Maintenance Manuals, Parts Lists, Concept of Operations, and about 20 other documents that describe the system you built.

These are the metadata for a mechanical engineering artifact. They are less like comments inline with code than they are similar to Dave Winer "worknotes" -- external documents linked from inline comments.

A diametrically opposite point of view is represented by Slashdot reader ShanghaiBill, who writes: "Every comment you leave in your code is an admission of defeat." Guided by Robert C. Martin's 2008 book Clean Code, this programmer adheres to the philosophy that each comment simply means that "you were unable to write your code clear enough to eliminate the need for the comment."

I believe this latter view can't be right. Code itself cannot embody all the metadata that could possibly be of value to someone encountering the code at a later time. I would err on the side of Donald Knuth's literate programming, whose main idea to "treat a program as a piece of literature, addressed to human beings rather than to a computer." First you describe what your program is going to so; only then do you tell the computer how to do it.

As a coda to the commenting meta-commentary, enjoy the answers provided by the Stack Overflow community to the question: "What is the best comment in source code you have ever encountered?"