October 6th, 2025
0 reactions

Code comments should apply to the state of the system at the point the comment “executes”

Raymond Chen
Raymond Chen

Comments inside the body of a function should apply to the state of the system at the point the comment “executes”.

Here’s an example of poor comment placement:

// Widget is already vibrating, so we update the waveform in place.
// Else the waveform parameters will be set when we start vibrating.
if (waveformParameters != null) {
    waveformParameters.Shape = WaveformShape.Square;
    widget.UpdateWaveformParameters(waveformParameters);
}

When I encountered this comment, I read it as telling me that the widget is already vibrating. I’m thinking, “How do I know that it is vibrating? Shouldn’t we be checking for that first?”

And then I see the “else” part of the comment, and I get more confused, because why are we talking about what we do if the widget is not vibrating, if the previous sentence told us that we (somehow) already know that that it is vibrating?

Next, I see the if statement, and now it’s checking whether something is null, which I guess tells us whether the widget is vibrating. But the first sentence of the comment said that we knew that it was vibrating.

Oh, I see. The comment is really describing what we know to be true once we are inside the if block.

Here’s a less confusing way of writing the comment.

if (waveformParameters != null) {
    // Widget is already vibrating, so we update the waveform in place.
    waveformParameters.Shape = WaveformShape.Square;
    widget.UpdateWaveformParameters(waveformParameters);
} else {
    // Nothing to update right now. We will set the parameters
    // the next time we start vibrating.
}

Each comment describes what happens when execution reaches the block of code it is in. I even created a dummy else block to hold the explanatory comment about why it’s okay to do nothing.

If you really want to put the comment prior to the “if” statement, you need to structure it to match the state of the program prior to the “if” statement.

// If the widget is already vibrating, then update the waveform in place.
// Else the waveform parameters will be set when we start vibrating.
if (waveformParameters != null) {
    waveformParameters.Shape = WaveformShape.Square;
    widget.UpdateWaveformParameters(waveformParameters);
}
Category
Old New Thing
Topics
Code

Author

Raymond Chen

Raymond has been involved in the evolution of Windows for more than 30 years. In 2003, he began a Web site known as The Old New Thing which has grown in popularity far beyond his wildest imagination, a development which still gives him the heebie-jeebies. The Web site spawned a book, coincidentally also titled The Old New Thing (Addison Wesley 2007). He occasionally appears on the Windows Dev Docs Twitter account to tell stories which convey no useful information.

3 comments

Sort by :
  • IS4 4 hours ago

    I settled on this reasoning a few months ago; glad to see my decision validated!

  • Melissa P 5 hours ago

    not a huge fan of any of those comments because it doesn't explain the relationship between "already vibrating" and "waveformParameters != null" .. a better comment would be "if we have waveformParameters (therefore the widget is already vibrating), we update in place; otherwise it is done later when vibration starts" ... comment language should be fluent, using "if then else" is a bit robotic, so I dont see an issue with mixing it up to "if, otherwise"... in rare cases if the logic is a bit complicated (negated), using "unless" instead of "if" works too... a comment should only exist...

    Read more
    • Raymond ChenMicrosoft employee Author 4 hours ago

      I agree that the relationship between “already vibrating” and “waveformParameters != null” is implicit. The issue I was trying to illustrate was the comment placement, not the comment wording (which also could use work).

Read next