Commenting your code for speed reading

This post is more than 15 years old.

Posted at 07:30 on 01 September 2008

Here are a couple of important facts about code that you write, that many developers tend to overlook:

  1. You will spend much more time reading it than writing it, often after not having looked at it for months.
  2. Other people will also have to read it.

With this in mind, where possible, I like to use a coding style that helps me to speed-read my code. The idea is that you should be able to scan through a source file, picking out individual methods very quickly, and go from a grand overview of what's going on to a detailed look at individual methods. It's a style that I first picked up at university when looking at another developer's code, and I'm yet to see anything that (in my humble opinion at any rate) beats it for clarity. It looks like this:

/* ====== MyMethod ====== */
 
/// <summary>
///  XML comment goes here
/// </summary>
/// <param name="str">
///  A <see cref="System.String" /> which is passed as a parameter
///  to your method.
/// </param>
/// <returns>
///  An integer, representing something or other returned by your
///  method.
/// </returns>
 
int MyMethod(string str)
{
    // do something
}

The key features are as follows:

  1. The method signature is prefixed by a header comment and an (optional) doc comment block.
  2. The header comment consists of the method name surrounded on each side by six equals signs.
  3. There are two blank lines before the header comment, one blank line between the header and the doc comment, and one blank line between the doc comment and the method signature.

This may sound pretty pedantic and exacting, but it's just my style, and I find it clear, crisp and very effective for the purpose. There are of course other similar variations on the theme, so it's more the principle that matters rather than the exact details. Highlighting the name of your method or property in a header comment in particular works wonders: you can page through your source file in seconds, and perhaps even relax the focus in your eyes a bit, and zoom in on the method you're after very quickly. The decorative equals signs draw attention to the text of the headers without overwhelming them, which means you can pick them out and read them in a fraction of a second when you're scanning through your source code.

One thing that I'm not too happy about, however, is the XML documentation comments that Microsoft has come up with for C# and VB.NET. The angle bracket tax gives you a whole lot of visual clutter to deal with. Javadoc and PHPdoc style comments seem much more elegant and simple:

/* ====== MyMethod ====== */
 
/**
 * Doc comment goes here
 *
 * @param str
 *  A String which is passed as a parameter to your method.
 * @returns
 *  An integer, representing something or other.
 */
 
int MyMethod(string str)
{
    // do something
}

Some developers tend to go a bit overboard with decorative bits and pieces on their comments. This is a real-life example from a PHP date/time library that I have encountered:

//==============================================================================
// +---------------------------------------------------------------------------+
// | Function: getMonthName                                                    |
// +---------------------------------------------------------------------------+
// | Accepts:  Nothing                                                         |
// +---------------------------------------------------------------------------+
// | Returns:  The name of the month                                           |
// +---------------------------------------------------------------------------+
// | Description:                                                              |
// |                                                                           |
// | Returns the name of the month of the timeStamp                            |
// +---------------------------------------------------------------------------+
//==============================================================================
    function getMonthName()
    {
        return date('F', $this->_timeStamp);
    }
 
 
//==============================================================================
// +---------------------------------------------------------------------------+
// | Function: getWeekDayName                                                  |
// +---------------------------------------------------------------------------+
// | Accepts:  Nothing                                                         |
// +---------------------------------------------------------------------------+
// | Returns:  The name of the weekday                                         |
// +---------------------------------------------------------------------------+
// | Description:                                                              |
// |                                                                           |
// | Returns the name of the week day of the timeStamp                         |
// +---------------------------------------------------------------------------+
//==============================================================================
    function getWeekDayName()
    {
        return date('l', $this->_timeStamp);
    }

Very pretty, but the decorations on the comments dwarf both the code and the comments themselves somewhat. Personally I find it slower to scan -- partly because the comments take up more space, which means you get less code on the screen at the same time, but also because it looks rather distracting. The difference is only a fraction of a second for each method, but it does add up in a big class.

Besides, that kind of bling is a complete faff to type.

Needless to say, this isn't the only thing you need to do to make your code easy to read. You also need to choose sensible method names -- not too long and not too short -- that describe what your method does as precisely and clearly as possible within about 30 characters or less. Consistent indentation is also pretty important (Visual Studio is great in this respect -- it does it all for you if you press Ctrl-K, D) as is keeping your line length down to something sensible. I find that the maximum line length you can sensibly get away with is about 96 characters: beyond that, you start to have to scroll horizontally all over the place, and your lines wrap when you try to print it out. Oh, and if you use the visual designers in SQL Server Management Studio, please tidy up the resulting SQL after you copy and paste it into your stored procedures. Otherwise you are making life difficult for whoever comes after you who has to understand and maintain the stuff.

What do you think? Do you use any particular stylistic conventions on your comments, or do you find incremental search, document outlines, syntax highlighting and code folding sufficient? Can my style of commenting be improved on?