Core Documentation Philosophy Wars

Perl 5's recent improvements to project management (migration to a public and distributed source code management system, monthly development releases, and yearly stable releases) have spurred on other improvements. For example, I've decided that I'm looking forward to implicit dereferencing from prototyped operators in Perl 5.14.

Some of the other improvements are less obvious and less dramatic. Chas. Owens has been revising perldoc perlop to improve its accuracy and organization. Much of the core documentation has accreted over the years—not just sundry and (in the gestalt) jarring additions, but various programming styles as well.

I've submitted patches at various times to replace certain specific deprecated code styles with improvements. I'm not the only one. Granted, it takes little work to convince a committer that removing examples of pseudohashes, 5.005 threads, or indirect constructor calls can improve the documentation for people using 5.12, but even such patches are not without controversy.

A recent thread on p5p started with a patch which went further. One spot of controversy was the replacement of global bareword filehandles with lexical filehandles. Another point of contention is the value of declaring all variables as lexicals.

One philosophical stand suggests that the documentation for any given version of Perl 5 should reflect the best practices as understood for that version of Perl 5. In other words, if Perl 5 users should prefer lexical filehandles over local-scoped globs in 2010, the documentation in 2010 should do so also.

One objection to this idea is that the documentation will be in a constant state of churn as some, many, or most (pick how fat you stuff your straw man) best practices are mere fashion. You can imagine, some argue, strewing references to inside-out objects throughout the core documentation in 2006 or 2007. How silly would that look now?

The other philosophical position suggests that the consistency of a single coding standard throughout the thousands of pages of documentation is a foolish hobgoblin's goal, that any example (whether written in the Perl 4 or 1 days) that remains working in bleadperl does not need patching, thank you very much, and that novices benefit from the very expression of TIMTOWTDI in the documentation.

The strawman objection to that argument is that that argument is basically "Don't tell me I'm coding wrong!"

Me, I'm somewhere in between. Critics often complain that coding Perl 5 well means understanding every possible way that someone might code something. That's obviously false on its face, but TIMTOWTDI is a pragmatic admission that no single WTDI is obviously superior in every case. (Want to start a bar fight? Ask three different people when it's okay to use unless.)

Even so, I think you also have to be foolish (if not outright malicious) to suggest that novices should prefer things like global filehandles to lexical filehandles. Everyone knows that whatever's in the documentation gets copied and pasted and tweaked until it works, and if the original source has bugs or malfeasances or security errors or subtle tricks that will only hurt the coder several months down the road... well, perhaps the documentation should aim a little higher than that.

You won't catch me producing a bleadperl-wide vertical alignment patch, nor will you see me slapping my on all variables in even a single POD file. Yet improving the example Perl 5 code which will get repeated ad infinitum in the world is a good goal, and no piece of existing documentation is so sacrosanct that it does not bear the critical eye of someone asking "Is this the best way to write this example with Perl 5.12 or Perl 5.14?"