.. my experience is that if the documentation is not next to the code, people are much less likely to read the documentation when looking at the code ..

Mmm, that's a matter of opinion. The POD should contain enough information for someone using the module to write code that uses it. If they also have to look at the code, that's a problem with the POD.

Hmm, I'm not sure I agree that my experience is a matter of opinion. :)

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.

A typical workplace example is that 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, rather than determining that from the documentation of the method. Having the documentation right there when they look at the implementation is one small way to help them avoid that error.

It would be poor software craftsmanship to update the code without updating the POD.

Yes. Sadly, some human software developers are not perfect. We should do what we can to help them overcome their imperfections - to make it as easy as possible to do things right. Having docs next to the code it describes is one small way to make it easier to do things right.

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?'

Alex / talexb / Toronto

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

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~

The POD should contain enough information for someone using the module to write code that uses it

But this module currently only has me using it. As I said in the question, it is a utility module that will never be published. The reason I am adding POD is to help me remember what what all the methods do without having to keep diving into the source code to look at comments and inspect the code.

We will almost certainly bring on another developer at some point. But even then, I don't expect this module will ever have the same level of POD detail as I would apply to a module that was destined for CPAN.