in reply to Where to place POD

For my code, i usually order it this way:

  1. hashbang or package name
  2. global use statements that are common to all pm files ("autopragmas" that can get updated by a script)
  3. local use statements
  4. package constants/variables
  5. new() function
  6. all "main"/high level functions
  7. helper functions
  8. __DATA__
  9. __END__
  10. POD

Basically, the more "important" higher level stuff goes first, the lower level stuff goes lower, the optional stuff comes last. Makes it slightly more inconvenient to updates documentation, if i add one at all; a lot of my internal, for most of my personal use stuff i don't even bother. But when debugging/changing/enhancing a perl module, i look for the high level stuff first and only go into internal helpers later, if at all.

For debugging (no matter if it's my code or someone else's), a lot of the times the POD is either useless are plain wrong. You know, it either describes the behaviour that the code should exhibit but doesn't, or the POD is outdated. So that's the part of a file i rarely look at, therefore it goes at the bottom. And unless i want to actively change the POD, i nearly always look at the documentation generated from the POD (man pages, metacpan), not the POD itself.

But that's just how i handle POD. There is no "best" way. If you are unsure, just try a few different ways and see what you like best.

PerlMonks XP is useless? Not anymore: XPD - Do more with your PerlMonks XP