Beefy Boxes and Bandwidth Generously Provided by pair Networks
Problems? Is your data what you think it is?
 
PerlMonks  

Comment on

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

But this problem with docs and code getting out of sync is a real one, and my personal experience (because I can be in-the-bad-way lazy) is that the docs suffer if I don't do inline POD.

You are definitively right here. My personal (bad?) solution to this problem is to write documentation for the user aspect of a module only - and for this I find the "doc writing code sweep" approach quite OK, since the user interface should not change often anyway.

For the rest, I use comments. All in all, I mostly try to write "self-documenting code". But alas, I am not the one to ascertain if I succeed in this.

The worst problem with all this, IMHO, is that there is really no other way to document the interface to your function in the code than by clever paramater naming. And even that is in vain for return parameters. And that in a language that can have an arbitrary number of them, and without types. This is a really weak point in Perl (no way to express function signatures with return types in the code).

What I found in practical work is: you really need to read the code you call. If something does not work as expected, and you are sure your code is not the problem, go and read the code you call (with a nice debugger this is much easier than one thinks).

Christian Lemburg
Brainbench MVP for Perl
http://www.brainbench.com


In reply to Re: Re: Re: Inline POD vs. EOF POD by clemburg
in thread Inline POD vs. EOF POD by lachoy

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 lurking in the Monastery: (8)
    As of 2014-12-27 17:39 GMT
    Sections?
    Information?
    Find Nodes?
    Leftovers?
      Voting Booth?

      Is guessing a good strategy for surviving in the IT business?





      Results (177 votes), past polls