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.
Personally, I prefer your last case. I put comments before my functions that explain in plain text what the function is doing, e.g. "If the widget is vibrating, do X; otherwise, do Y". If the function is particularly complex, I'll put more comments inside it that explain how it's accomplishing that, but I like being able to just see at a glance a summary of the function's... function, without scanning the whole thing for comments. It's like the index of a book. You quickly scan to find the page with the thing you're interested, then you read that page in detail.
I handle comments for blocks of code like functions (besides nor arguments). Sometimes this commenting style opens my eyes to abstract it away or just to create a named function call in place. Depending on context and rest of the code off course. Comments should be high level for blocks. I try to avoid any commenting for single line. Sometimes line comments are signs to restructure or rename stuff.
For if blocks, when needed (first try to avoid the need for comments) a summary at top is added. And only then if needed, in each sub-block (under if, or else if or else) parts comments could be added, for additional context. I probably break my rules more often than I should, but that's at least my goal.
IME, single-line comments that deserve to stay are ones warning about unobvious context, like why a certain function call has funky parameter prep, or why a var is being treated differently, or even just a healthy reminder that 'this' math statement does actually need all those type casts.
Of course, if I find myself simply stating only what the code is doing, I'll look for things to restructure/rename (because why the F did I feel the need to write a comment if it's straight forward?), but they're useful far more often than certain types ("code should be self-documenting!") like to admit. Hell, some code ends up looking funky solely because it's using a weird language feature or working around a language-specific issue and those usually-obvious things still sometimes deserve comments!
Just like how simple, elegant psudo-code can explode in to a mess when dealing with the real-world edge cases, sometimes simple code does deserve an explanation. Give the dev enough context to connect the simple conceptual idea to the complex state during the code's execution.
Only time I remove such comments is when they're referring to something that is already well documented somewhere. Like if it's a method call with some funky parameter requirements, but they're already thoroughly explained in the method's own comments/docs, then that might get removed. Still though, if it's funky enough that a coworker might have similar refactoring thoughts should they come through on their own, I might leave/add a comment about why the crappy statement(s) remain as they are (with reference to any docs) so the coworker doesn't have to literally re-search why the code wasn't refactored last time through. Promise it's not 'cause I'm lazy!!