Damian Conway gave a tutorial in 2004 titled “Best Practices Perl”
that describes a series of best practices concerning programming Perl
applications. (Mike Kruckenberg
wrote up a review
of the presentation.) I agree with most of his points, but I do have
a bit of a problem with the section of POD documenting. Damian
mentions that: “put POD after END since the parser doesn’t have to
parse the POD.”
I can agree with Damian’s point about not needing to parse the lines,
but normally you would have comments there anyway. I believe it’s
better to have the documentation in POD format rather than as
comments. There is no appreciable difference in parsing speed between
parsing POD and parsing comments.
Damian’s point that POD documentation at the end does not need to
follow the layout of the code does have merit, but I believe it is
outweighed by the need to keep code and documentation in sync. With
the documentation as close as possible to the actual code it is easier
to keep them aligned.
Finally, if performance is most important then all POD and all
comments should be stripped from the files before placing in
production. This would eliminate all parsing time. I would
argue that this may be a good trade-off in specific instances, but
not in general.
All told, I would recommend any Perl programmer picking up a copy of
Damian’s book
Perl Best Practices
and incorporate those ideas they feel comfortable with. Highly
recommended.
