This practice is simple, and probably covers a lot of the places I appear to have been waffling between one view and another. The book says to comment anything that puzzled or tricked you. Pretty simple? The questionable part is that everyone will find different issues tricky.
The book provides an example:
$build_mode = oct $arg{mode}; # *From* octal, not *to* octal
The comment there is to remind you that octal reads an octal value and returns an integer, rather than converting to octal. Apparently this catches people, as they assume it returns the octal value.
Commenters have pointed out that I have suggested both “write things and be clear” and “don’t describe everything about how the language works”. This is a fine line, and I don’t know how to best describe how it should be described, and where the point that the comments are useful begins, and where they just get in the way.
The book says, simply, do it when you gat caught. A fine, followable rule, but one that only works for you. The hope is that your “Doh!” moment will be prevented next time, and that another engineer won’t have it either. The goal isn’t to try and prevent every engineer’s from having every possible problem. If they get tricked by something in the code, they should add a comment. Don’t try to guess what other people might find hard; just document what you had trouble with. Eventually, it’ll be clear enough for the people working in it.
It’s a pretty good theory, and a reasonable guideline.
The only problem I have is when someone with a different skill set writes code and I wind up reading it. They are potentially commenting Perl constructs that I find obvious, because those constructs are less familiar to them. They also potentially don’t comment things I would benefit from seeing a comment on. I wind up simultaneously thinking, “Of course that’s what that does” and misreading the code myself. An extremely effective combination which I run into regularly.