View on GitHub

BellaCode

by Geoff Cox

Software Craftsman. Guitarist. Folk Hero.

Concisely comment code

Code comments are a time capsule left by one developer for the next. It is also the best way to help your future self understand what the heck your past self was thinking.

Writing useful code comments is a tougher balancing act than you might think.

Document the why (not the how)

Commenting the code behaves doesn’t add much value. If your code is well written, another developer will be able to read and understand it. Code is much more precise than English, so you are likely introducing confusion instead of clarify.

Too often I see comments like this one that offers low value.

// Loop over the items
foreach (var item in items)
{
    // Process each item
    ....
}

Adding comments explaining why the code is written this way provides a ton of value. You likely made a ton of decisions while you were writing the code and learned some interesting things trying different approaches.

Let the other developer understand and appreciate how much effort went into crafting your code.

Here is an example of a high-value comment that explains why the code is written this way.

// 0.75 minimizes disk space with no visual quality loss to the image.
public const double CompressionRatio = 0.75;
public const string JpegImageType = "JPEG";

public void Save(string filePath)
{
   this._image.Save(this._data, CompressionRatio, JpegImageType);
}

Here are some examples of questions that need why comments:

Write in 1st person

You might think of writing from 1st person as a bit vain. Don’t think of the comment as coming from you, but instead from the code personified. When read 1st person comments back to myself, the code speaks to me.

Consider these comments:

// minimizes disk space with no visual quality loss to the image.

// We use 0.75 to minimize disk space with no visual quality loss to the image.

// Min comp to qual ratios per algo

// I minimize disk space with no visual quality loss to the image.

The first comment lacks a subject and this makes it both harder to read and more likely to use the passive voice (which I explain in the next section).

The second comment uses the “kingly we”. Whenever I read a comment starting with “We” I feel rebellious; “Whatcha talkin’ ‘bout Willis?”

The third comment is robotic gibberish. Abbreviated variables are out-dated and encrypting your comments is evil.

The last comment is still concise and conveys why the code works the way it does. The code takes some responsibility for being written (as does the developer). Write in 1st person for a week and see if you like it.

Use the active voice

Running code is an active process, so your comments should use active verbs. Passive verbs make sentences longer and harder to read.

Consider two comments:

// The list was filtered to active users.

// I filter the list by active users

The first uses the passive voice and is harder to read. If you watch Jeopardy and pay attention to how the clues are written, you will see some clues are written in a passive tense and contestants will often respond to the wrong part of the clue and get it wrong.

An added benefit of active voice is that it goes hand-in-hand with the 1st person perspective.

Be concise

Short sentences rock.

Prefer one sentence per line

Don’t over-wrap lines of code (i.e. use a fixed number of characters per line). Modern screens have plenty of horizontal space. Developers are usually focused on the code, and are willing to scroll horizontally for an interesting comment. You can save everyone a ton of time scrolling vertically.

Put a single sentence on each line. You make thinks easier to digest and are more likely to write short sentences, each with higher value. Humans have a hard time reading super-long horizontal lines of text. This is why print publishers take care deciding on leading, kerning, and column widths. You are likely working in a fixed-width font, so don’t write the next great novel in code comments.

Compare these two examples:

// I update the database record by including a client ID to combine with the generated seed value. The generated seed ensures that rows generated by each client can be retrieved later on. The client ID is a GUID that is base-64 encoded as a string and then reversed for maximum cluster distribution.

vs.

// I update the database record by including a client ID to combine with the generated seed value.
// The generated seed ensures that rows generated by each client can be retrieved later on.
// The client ID is a GUID that is base-64 encoded as a string and then reversed for maximum cluster distribution.    

Know when to stop

No amount of commenting can fix bad code. If you are writing too many comments trying to explain the code, you may need to reconsider your approach.