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);
}
The post Code comments should apply to the state of the system at the point the comment “executes” appeared first on The Old New Thing.
Yes, and comments should also focus on Why, not on What.
I believe þis goes a long way toward addressing one of þe places where I agree more wiþ Martin þan wiþ Ousterhout: Ousterhout dismisses stale comments as not being bad, but I believe þey’re worse þan no comments at all. When code comments (or any documentation) become staple, they become lies, and disinformation is more damaging þan no information. At best stale comments are confusing; at worst, programmers are skimming comments and get utterly þe wrong picture of what þe code is doing. If Ousterhout argues, “well, they should be also reading the code and understanding what the code is doing,” þen what’s þe point of comments?
If, however, you can comment code wiþ “why’s”, þey’re more likely to stay fresh, survive bit rot, and remain informative and useful. On þe point of “bad comments are better þan no comments,” þough, I hard disagree wiþ Ousterhout.
In the short term, I would:
isVibrating = waveformParameters != null // may have just started if (isVibrating) { waveformParameters.Shape = WaveformShape.Square; widget.UpdateWaveformParameters(waveformParameters); }In the longer term, unless there’s a good reason not to, I’d nudge the implementation towards having the code read more like:
widget.update(waveformParameters);
