Beefy Boxes and Bandwidth Generously Provided by pair Networks
"be consistent"

Comment on

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

One of the biggest differences between POD and comments for me is that comments don't look like code while POD is not easily visually distinguished.

One of the nice things about POD is how easily and naturally you can include sample code in your POD. So I find it very likely that sample code will get included in POD. And trying to read the actually code when it is shuffled together with POD that includes sample code actually feels like a nightmare &emdash; like I'm just going along opening this innocent-looking file of Perl code and suddenly I realize that it is "finals" and I haven't studied and then everybody is laughing at me because I'm also naked, er, I mean, I suddenly realize that I can't even find the code.

Because, instead of the file containing a block of code that I can read or scan or scroll through or search through, the file contains some twisted "scavenger hunt" where I think I've found some code but it is really just text that looks like code. And when I find the code, I have a hard time concentrating on it to understand it because I'm not confident that I really did find it this time.

Because whether "code" is really code or not depends on whether one of the hundreds of '=' characters in the previous 10 pages happens to be in the first column and also whether that closest prior such '=' is followed by 'cut' or any other word.

Comments require that the fairly distinctive '#' be present on every line. POD actually requires that the ubiquitous '=' character be separated from what you are looking at by at least one blank line.

But even without embedded sample code in your interleaved POD, I find that the POD can greatly interfere with the reading of code, especially for some types of reading (especially less linear types). So please don't interleave POD and code.

Yes, I understand the theory of "keep the documentation close to the code so that when somebody changes the code they'll also change the documentation". But I don't believe it actually works that well. The documentation gets updated most when the documentation gets used. So I think you get better results by concentrating on writing useful documentation.

And it is easier to make documentation useful when you can structure the documentation usefully, not be constrained to a structure that makes sense when shuffled together with your code.

So use comments to explain things that somebody trying to read the code needs to understand. Use POD to write documentation to be used by people who are trying to make use of your code. Quite different audiences who want quite different information. And keep the POD away from the code (such as after the __END__ marker or in a separate *.pod file).

- tye        

In reply to Re: Documentation: POD vs Comments (visual) by tye
in thread Documentation: POD vs Comments by ravenclaw

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, 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
  • 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.
  • Log In?

    What's my password?
    Create A New User
    and all is quiet...

    How do I use this? | Other CB clients
    Other Users?
    Others browsing the Monastery: (7)
    As of 2018-06-23 03:31 GMT
    Find Nodes?
      Voting Booth?
      Should cpanminus be part of the standard Perl release?

      Results (125 votes). Check out past polls.