Beefy Boxes and Bandwidth Generously Provided by pair Networks
Pathologically Eclectic Rubbish Lister
 
PerlMonks  

Comment on

( #3333=superdoc: print w/ replies, xml ) Need Help??

POD is documentation for the *user* of your code. That could be an end-user, or it could be a programmer who is using your code. POD should document what the code does.

Comments are documentation for the *maintainer* of your code. Comments should document how the code does what it does. So for example it documents the algorithm and anything else that might not be immediately clear to a maintainer.

So, for example, in this module the POD simply tells you what methods exist, what arguments they accept, and what they return, and then there are comments like:

# we override these in the test suite to avoid having to be root ... sub stat { return CORE::stat(@_); }
but that subroutine isn't even mentioned in the POD. It's not something that a user needs to care about.

Then in the subroutine that does the bulk of the work there are small comments every few lines that explain all the steps in the algorithm:

# if a user has been specified, first get their UID (from their # username if necessary). ... # now divine the user's permissions. first get the file's mode # bits and ownership ... # now check user/group perms. Set isReadable etc if the mode has # the owner bit set and the user is the owner, or has the group bit # set and the user is in the right group ... # root can read and write anything, can execute anything # with any x bit set

As an aside, I'd note that comments are really only useful in conjunction with the user-level documentation. Maintainers needs to know both what the code is supposed to do and how it does it. Therefore you make the maintainer's life easy by putting POD as close as possible to the bits of code that it documents. Scattering POD inline with code is Good, putting it all at the beginning or end of the file, separate from what it's documenting, is Bad.


In reply to Re: Documentation: POD vs Comments by DrHyde
in thread Documentation: POD vs Comments by ravenclaw

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!
  • 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, 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, sup, table, tbody, td, tfoot, th, thead, tr, tt, u, ul, wbr
  • Outside of code tags, you may need to use entities for some characters:
            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.
  • Log In?
    Username:
    Password:

    What's my password?
    Create A New User
    Chatterbox?
    and the web crawler heard nothing...

    How do I use this? | Other CB clients
    Other Users?
    Others contemplating the Monastery: (11)
    As of 2014-08-21 21:28 GMT
    Sections?
    Information?
    Find Nodes?
    Leftovers?
      Voting Booth?

      The best computer themed movie is:











      Results (143 votes), past polls