The Principle of Gentle Tutorials

Sometimes I bless function references.

I've blessed scalars and array references. Someone help me, I've even blessed typeglobs. Sometimes I've had good reasons to do so, and sometimes I did it merely because the feature was available. I've monkeypatched (and actually patched) UNIVERSAL, the base class from which all Perl 5 classes inherit. I've built my own object system. I've abused AUTOLOAD and worked around bugs in Perl 5's SUPER.

Yet the chapter introducing object orientation in Perl 5 in the Modern Perl book introduces objects in terms of plain vanilla Moose. Only after readers are happy and productive with Moose and attributes and roles does the book pull back the Moose curtain to reveal blessed references.

Why?

It's been a few months since the previous debate on the Perl 5 Porters mailing list over what tutorials should cover (or whether tutorials should exist). The current sound and fury nominally centers on a patch to improve perlopentut.

One side of the debate decries replacing examples of the two-argument open and the use of bareword filehandles (package globals) as bowdlerization and whitewashing and even an attempt to excise two-plus decades of working Perl code as clunky and out of favor. Another side of the debate suggests that encouraging novices to write code in a style that minimizes accidental flaws (I didn't write eliminate) is more important.

Other positions and nuances exist, yet the schism seems to be over what's in favor.

Certainly some novices will eventually encounter code which uses the two-argument open for a good reason, whether it's working and safe code that hasn't needed maintenance and thus has no compelling reason to revise it or whether there's a very specific and documented reason why the newer approach will not work. The core documentation must somewhere document all three variants of open (the one-, two-, and three-argument forms).

Yet why should that primary source of documentation be in a tutorial, aimed at novices who lack, by definition, the experience necessary to choose one approach over another in terms of safety, correctness, maintainability, and the ineffable bits of magic that only experience can provide?

After all, it's possible to overwrite files when you intend to open them for reading if you're not explicitly careful about how you use the two-argument open in Perl 5. Yes, I know that if you can't trust your filesystem or the other users using your filesystem you're open to all sorts of security holes, but I make a habit of not trusting myself because I make all sorts of stupid errors.

I'm sure it's possible to use the two-argument open in a safe, sane, and secure form, but I avoid it whenever possible because I don't trust myself to get it right every time. The same goes for my uses of global variables or monkeypatching or tie or indirect method calls or most uses of prototypes. I might feel slightly better if I lose important data due to my own stupidity and not a remote exploit, but I've still lost important data.

I'm glad that other people are smarter or more disciplined or more careful than I am, even after my thirteen years of experience with Perl, countless articles written and edited, a handful of books, several projects, and dozens of CPAN distributions. Yet I look at, for example, the documentation on php.net for the simplest function and I see buggy, incomplete, insecure, and confused code and I think sometimes that encouraging novices to write what some might consider to be unnecessarily strict and simple code that doesn't force them to understand everything that might possibly go wrong might be an act of compassion and kindness.

(Also interpreting part of the name of a file as an access mechanism for a file with a different name—RT #64504—is an example of why the magic parsing of unstructured data is a sin.)