Coding Horror: Jeff Atwood and his periods

Last night, I was seated at a table in Fresno State's University Business Center, alongside some of the city's finest developers: Raj Muthusamy, Mike Vea, and Borland Delphi Guru Constant Yang—the opposite of Yin, but more consistent. We had one empty seat at our table, but it was reserved for Larry "Be-Right-Back" Kalpakoff.

We were watching a demonstration by Coding Horror Author Jeff Atwood and Scott Stanfield, the CEO of Vertigo Software, when someone behind us started a discussion about "periods".

"He has periods in his single-line comments," someone said. Others gasped.

From then on, I was completely distracted. Instead of really absorbing the presentation, my mind kept thinking about commenting code and all of other debatable "best practices" in our industry.

The presentation was on Silverlight and Microsoft's WPF (not to be confused with Microsoft's WTF—code name for the ill-fated Microsoft Bob). It was a great presentation—one of those that get you really fired-up about new technologies.

Incidentally, I could see the Delphi influences everywhere. It seems Microsoft's acquisition of Borland's top programmers really paid off. I was particularly fascinated by the evolving of Delphi's now XML-based DFM files into something called XAML. I will discuss that more in a later post, but for now, let's air out this commenting issue.

Take a look at this code...

void ReadFromFile ( string fileName )

 {

  try

  {

   // read from file

  }

  catch (FileIOException ex)

  {

   // log error

   // re-throw exception if required

   throw;

  }

 }

From the examples we saw last night, the Vertigo Software team might have written it like this...

void ReadFromFile ( string fileName )

 {

  try

  {

   // Read the data to be imported from the file.

  }

  catch (FileIOException ex)

  {

   // Log the error appropriately.

   // Re-throw the exception if it is required.

   throw;

  }

 }

See the difference? Both sides of the argument agree that periods and proper capitalization should be used when more than one sentence is needed. The disagreement occurs when only one sentence or phrase is sufficient.

Not really worth arguing over, huh?

I've seen programmers argue over the proper use of the semicolon for years. It was inevitable that the period debate would begin sooner or later.

The argument is really not about anything you're hearing on the surface. This argument is about code readability.

Valuable maintenance time is saved when a programmer can understand code quickly. Readability of code is determined by a combination of the code and the comments used. Unfortunately, what appears easier to read and comprehend for one developer may not be easier to read and comprehend for another.

DK Rukovsky explains:

"...I think that primary reason to write comments is to make your code understandable for others. The rule is simple. If you hide your code forever, nobody is going to care if it is commented properly or not."

That's how these debates always start.

There are debates about how many blank lines should exist between methods and whether comments belong above or within functions and procedures.

As for Vertigo's insistence on complete sentence structure, I believe it originated with the various C# Style Guides that have come along. Here's a quote from the Bellware version:

"Use complete sentences when writing comments. Comments should clarify the code, not add ambiguity."

Folks in the complete sentence structure camp may take this type direction more literally from those in the other camp. Some of those folk believe that using more than a single line of comment in one place should be the exception to the rule.

Peter Elst, a programming consultant, wrote:

"If you need more than 5 lines of comments to explain how to use a method you might want to consider refactoring the method."

I suspect that the use of overly verbose comments could also be prompted by an expected move to XML Comments or something similar. If the comments will ultimately be extracted and live in user documents or help files apart from the code, they might require complete sentence structure to be understood.

    /// <summary>

    /// This class contains static utility functions for use 

    /// </summary>

    /// <remarks>

    ///        <para>As we develop general-purpose utility functions,

    ///        <para>The current utility functions include:</para>

    ///        <list type="bullet">

    ///            <item><see cref="FixQuotes" /> to fix up SQL 

    ///            <item><see cref="ReplaceNull" /> to convert nulls

    ///        </list>

    /// </remarks>

But, of course, there is another side to that story, as well...     

The team at the C# Code Project advises against verbose comments for any reason:

"Do not write comments for every line of code and every variable declared. Write comments where required, but true readable code requires few comments. If all variables and method names are meaningful, the code is very readable without verbose comments. Less lines of comments make code more elegant, but if the code is not clean and readable and comments are scarce, that is far worse."

Wikipedia adds:

"Some contend that comments are unnecessary because well-written source should be self explanatory."

We may never have a consensus to these arguments. We may never know when it's best to use a period and when it's not, but all do agree on one thing: Comments in source code are important. There is even a tool that can create comments for you—mimicking your personality.

Hmm—I wonder if I can get the source to that tool and adapt if for blogging—or perhaps e-mail auto-replies. Now, that sounds like a good challenge for WPF and XAML if ever I've heard one!