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

In reply to Re: Where to place POD by cavac
in thread Where to place POD by Bod

Title:
Use:  <p> text here (a paragraph) </p>
and:  <code> code here </code>
to format your post, it's "PerlMonks-approved HTML":



  • Posts are HTML formatted. Put <p> </p> tags around your paragraphs. Put <code> </code> tags around your code and data!
  • Titles consisting of a single word are discouraged, and in most cases are disallowed outright.
  • Read Where should I post X? if you're not absolutely sure you're posting in the right place.
  • Please read these before you post! —
  • Posts may use any of the Perl Monks Approved HTML tags:
    a, abbr, b, big, blockquote, br, caption, center, col, colgroup, dd, del, details, div, dl, dt, em, font, h1, h2, h3, h4, h5, h6, hr, i, ins, li, ol, p, pre, readmore, small, span, spoiler, strike, strong, sub, summary, sup, table, tbody, td, tfoot, th, thead, tr, tt, u, ul, wbr
  • You may need to use entities for some characters, as follows. (Exception: Within code tags, you can put the characters literally.)
            For:     Use:
    & &amp;
    < &lt;
    > &gt;
    [ &#91;
    ] &#93;
  • Link using PerlMonks shortcuts! What shortcuts can I use for linking?
  • See Writeup Formatting Tips and other pages linked from there for more info.