At YAPC::NA 2011, I whined about the lack of codification of tribal knowledge in Perl. One area that’s ripe for fixing is the documentation on open. There’s a section in perlfunc for open, and a tutorial: perlopentut. That tutorial is where I’ve started my campaign to have the tutorials and FAQs give good advice.
open has several forms, not all of which are equal. The standard usage in modern Perl is the three-argument open, which separates the open mode from the filename to open. This lets you stop worrying about how whitespace or other “odd” characters will be interpreted by open, and avoids having the shell interpret things.
Another standard usage is to provide open with a reference, rather than a bareword filehandle. Perl will automatically close these lexical filehandles when they fall out of scope. Since they’re lexical rather than global, there’s no risk of collision, and you can easily pass them like any other parameter into or out of a subroutine. It makes filehandles “normal” and that’s a good thing for beginners.
Unfortunately, perlopentut doesn’t emphasize these and other best practices. I submitted a patch that revised and re-ordered the tutorial to give the best information up front. This gives newcomers the best chance of picking up these good habits. My patch ignited a… “heated discussion” shall we say? It’s back to the drawing board for my revisions to the tutorial, but I’ve had an amazing amount of suggestions and useful criticism from many people on the p5p mailing list and in the blogosphere (a word I’ve never had the opportunity to use before). If you’re one of the constructive voices – thank you! I’ve had plenty of proposed revisions that seem to have widespread agreement, so I’ll be working on including as much as I can in a series of patches.
I hope I can digest the discussion and put together something more palatable that will give newcomers the leg up I didn’t get from perlopentut.