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??
This is an example of a well documented method:

=head2 insertRows($nameTable, $raRow) Insert the data in $raRow (array ref with hash refs (key: field name, value: field data) into $nameTable. Return 1 on success, else 0. Die on fatal errors. =cut sub insertRows { my $self = shift; my ($nameTable, $raRow) = @_;

It describes the interface to the method. So you don't have to read the code to know how to use it. But you need to keep it in sync with the implementation, so the POD should be next to the method (Locality breeds Maintainability).

If you write the interface description before you start coding the method, chances are that you'll think one more time about edge cases, error conditions and stuff like that. Personally I find that a very useful way of organizing my thoughts before diving in.

Names of classes, variables, and methods should be meaningful and consistent. That way you don't need so many comments. Try to avoid abbreviations.

I find it useful to include the "domain specific data type" in the variable name to indicate what it contains, especially when using dynamically typed languages.

$timeout vs $secondsTimeout $table vs $nameTable $workspace vs $dirWorkspace

When you do comment, note the why, not the what. Write down assumptions, thoughts and non-obvious design decisions.

Having said that, it is ok to say what a regexp does, because it's often not obvious. It's useful to provide a sample of what you're trying to match. Alway use /x to make it more readable.

If you look at CPAN, each module has a SYNOPSIS section with short examples. These are very powerful.

Apart from all other benefits with unit tests, they also provide great hands-on documentation, like a SYNOPSIS on steroids.

/J


In reply to Re: Preferred method of documentation? by jplindstrom
in thread Preferred method of documentation? by Anonymous Monk

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, 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?
    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 meditating upon the Monastery: (4)
    As of 2020-11-25 01:58 GMT
    Sections?
    Information?
    Find Nodes?
    Leftovers?
      Voting Booth?

      No recent polls found

      Notices?