I'd like to point out that there are actually three kinds of documentation in every Perl program, each of which serves different purposes.
In essence, all programs are communicating simultaneously with three audiences:
- The computer, which only cares that it receives an unambiguous set of instructions in some manner: whether that's elegantly-documented programming language translated by a compiler or interpreter or binary files makes no difference to the computer. For our purposes, we're using Perl, and beyond that the computer only cares that we have a Perl interpreter; it makes no judgements beyond "this program can read that one and tell me what to do" (anthropomorphizing wildly).
- The user of the code, who needs to know what the program does (or is supposed to do), how to make it work, and what the program can say about errors it knows how to detect. I prefer to use POD for this.
- Programmers: both the original author and anyone else who'll be reading the code to try to understand what was intended and how that was intended to be done. This is the point where there tends to be a lot of argument.
One thing that programmers tend to lose sight of at times is that what they do for a living is write things that can be easily read by others and are descriptions of what they intend the machine to do. Computer languages do not confer higher efficiency to what the computer does, but are used to communicate in a pidgin that humans can understand, and that the computer can turn into runnable sets of instructions which it can execute.
The code should make the implementation of your algorithm as clear as it possibly can on its own. If for some reason (efficiency, compactness of expression, or other important reason) the code is not going to be easily read by the intended audience, then it's necessary to add the third kind of documentation, comments, to do a good job. If you intended audience is very good Perl programmers, then maybe you don't need comments.
If it's meant to be read and understood by a different audience, then you need to make it so that it is understandable to them.
All modern code is documentation of the work to be accomplished; it's simply that we have a processor that makes a portion of that documentation executable by the computer. No one faults Knuth for writing dense mathematical analysis of algorithms; if you're reading his books, that at least in part is why you are reading them. They are, however, not meant for casual programmers or beginners with little math background; those folks would be better served with a different book - which would communicate different things, yes, but which would make sense to its target audience.
"WHALE SINKS BOAT, EVERYONE DEAD" vs. Moby Dick. Yes, they communicate the same information, but the novel transmits more useful peripheral information. Comments do the same, and sometimes I find that the peripheral information - why did I decide to do this? why did I want to do this? - can be just as important as what I actually decided to do.
Depriving yourself of this important avenue of communication to both others and yourself because you think "comments are useless" is misguided.
The argument I most often hear against using comments at all is "but the comments get out of sync with the code!" - they don't "get" out of sync. Comments are part of the code. If you are responsible for maintaining the code then you are responsible for maintaining the comments as well. I completely agree that bad or misleading comments are useless. It's simply that it's your job to fix them.
- If the code does not match the comments, fix the comments -- assuming the code is passing its tests.
- If the code is not working, the comments may be one of the few things that tell you anything about what was intended.
- If you make a set of comments obsolete, fix them - or if you're sure that the changes stand alone, then delete them - but only as a last resort.
- If the comments contain anything at all about the intent of the code, you should try to correct and preserve them; a comment is a signpost of possible complexity. Unless you've mitigated that complexity in a completely transparent way for all the intended readers, keep the comments.