I would look in the code for what operation was being performed, and see if I could figure out whether the code or the comment is correct.

From a form point of view, I would also use the postfix $i++ or $i-- because of my C background. Also, I only ever use single letter variables as loop variables -- there's too much opportunity for me to forget why I called a variable 'i'.

No comment of mine would ever duplicate just what the code is doing, without an explanation of what was happening.

# Add one to $i
$i = $i - 1;
[download]

Real world example:

This is a microcontroller environment, we are deep in the clock setup code. CPU clock and some other clocks are generated by a PLL, using a quartz as reference clock. Depending on how bits are set, the PLL stops if the lock to the reference clock is lost. If that happens, CPU clock stops.

SYSCTRL->DPLLCTRLB.bit.LBYPASS = 0; // keep running, even if lock is l
+ost
[download]

Well, the lock lost bypass bit should be set, not cleared, to keep the PLL running (with a slightly wrong frequency) without lock to the reference clock. This is the bugfix:

SYSCTRL->DPLLCTRLB.bit.LBYPASS = 1; // keep running, even if lock is l
+ost
[download]

Alexander

I would concentrate on getting the unrelated bug fix sorted...

But, I would probably add something along the lines of:

#################################
#
# Something is wrong here
# We need to resolve this
# 
# Search for what it's doing,
# check it's doing it right,
# then correct the code or
# the comment
#
#################################

# Add one to $i
$i = $i - 1;
[download]

If I came across that code in my own code while browsing for something, I would likely correct the case #2 comment to reflect the code, assuming that I had copy/pasted it from a similar comment elsewhere (e.g. the Case #1 snippet) while forgetting to adjust it to match the actual code. I might, or I might not--depending on my mood, change both of them to the shorter form of $i++ and $i-- respectively. This might depend on whether I thought it more readable in its explicit form, or whether or not I might have arrived at that equation from something else, which might again need tweaking later, such as $i = $i + 2; (which of course could be written as $i += 2; as well, but, again, this may be less readable, depending on the context).

My habit for a comment of that nature is just to remind myself of what the code is doing; less often do I intend for the comment to be prescriptive...and my comments are far more likely to be out-of-date than the code itself when I have returned and made adjustments.

If, however, I found that in someone else's code, I would scrutinize that more carefully to see what it should actually be doing and whether the code, or the comment, should be corrected.

Interesting. Would you consider deleting the comment?

👁️🍾👍🦟

I had assumed that your example was illustrative, and not necessarily the actual code involved. If, however, that were the actual code, of course I might just remove that comment! Too trivial to clutter my space with! There have been times, however, that I intended to share a piece of code with a friend who was learning how to code in Perl. Those are the times when something that trivial might have gotten into the code with purpose. So, I guess, it depends. Bad answer, I know, but in real life, context is everything. It's important to know first the reason the comment had been entered there.

Blessings,

~Polyglot~