Gripe about Perl Documentation

Perl documentation has an annoying habit of pretending to give a good example, when it actually gives you a completely useless example.

What tends to happen is they say something like “the following code will do the same thing as XYZ.” At first blush, that sounds useful. When you dig into it, though, it’s obtuse at best and useless at worst. If you really understand XYZ well, then they’ve probably told you something, but in an indirect way. Rather than tell you what it actually does, they’ve given you a pointer to something you could look up. In the worst case, if you don’t know what XYZ does, then they’ve told you nothing at all.

Lets look at some examples:

From perldoc -f unpack:

For example, the following computes the same number as the System V sum program"

If I knew what the System V sum program was (I do, but among the broader audience of all Perl users, that’s probably a small minority who actually know what sum does), then this would tell me something. But since the only comment is “slurp!” and the only description of what the code does is “the same number as the System V sum program,” this is useless documentation. It’s not like I can go get the System V sum man page online. Well, I suppose I could, but if I’m looking it up because I have no idea what “System V sum” is, how do I know I got the right man page?

From perldoc -f map

We learn that:

%hash = map { getkey($_) => $_ } @array;

is just a funny way to write

%hash = ();
foreach $_ (@array) {
  $hash{getkey($_)} = $_;

That’s great. I’m in the documentation because I don’t know how the function works. Instead of telling me what it does, I get “this opaque code does the same thing as this other opaque code.”

The other common gripe I have is that Perl is usually derided for being a “write-only” language. Perl code is very hard to read and understand if you didn’t write it yourself. The documentation writers give few good examples of readable code. Instead, they like to flex their obfuscated code muscles.

From perldoc -f open

The filename passed to 2−argument (or 1−argument) form of open() will have leading and trailing whitespace deleted, and the normal redirection characters honored.  This property, known as "magic open", can often be used to good effect.  A user could specify a filename of "rsh cat file |", or you could change certain filenames as needed:

$filename =~ s/(.*\.gz)\s*$/gzip −dc < $1|/;
open(FH, $filename) or die "Can’t open $filename: $!";

This is a great example of completely opaque code. (What does it do? Probably automatically unzips files that end .gz. The documentation doesn’t actually say.) Secondly, the actual example is a good example of a code injection attack. When prompted for a filename, the user could enter a command that would login on another server and fetch data from there instead. Whoops!

I think the standard perldoc documentation either needs to be abandoned and replaced with another source. Or, someone needs to go through that documentation and seriously rewrite it.