If someone comes to read the docs, I would usually expect that they'll use perldoc or similar. This is about people coming to look at the code.

Ah! If this is about people coming to update and/or fix the code, then I agree, they would look at the POD, and then go to the code.

I was thinking more about the situation where someone needs to use a module to get something done, without thinking about 'Gee, how does this all work?'

a developer picks up a bug report, analyses it to the point they see a method call somewhere clearly expecting some behaviour, and sees in the method that it does not implement that behaviour. They then make an assumption (effectively a guess) about whether it's the call or the implementation that is wrong

In my experience, it usually means they're both wrong. :-)

Pop quiz: what would you do if you stumbled upon these two code snippets while making an unrelated bug fix?

Case 1:

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

Case 2:

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

👁️🍾👍🦟

# 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

--
Today I will gladly share my knowledge and experience, for there are no sweeter words than "I told you so". ;-)

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.

Alex / talexb / Toronto

Thanks PJ. We owe you so much. Groklaw -- RIP -- 2003 to 2013.

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]

So, at the very least, it doesn't get lost in a mass of code again...

Regarding that "pop quiz":

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.

Blessings,

~Polyglot~

Interesting. Would you consider deleting the comment?

👁️🍾👍🦟