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.