Beefy Boxes and Bandwidth Generously Provided by pair Networks
We don't bite newbies here... much
 
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":



  • Are you posting in the right place? Check out Where do I post X? to know for sure.
  • Posts may use any of the Perl Monks Approved HTML tags. Currently these include the following:
    <code> <a> <b> <big> <blockquote> <br /> <dd> <dl> <dt> <em> <font> <h1> <h2> <h3> <h4> <h5> <h6> <hr /> <i> <li> <nbsp> <ol> <p> <small> <strike> <strong> <sub> <sup> <table> <td> <th> <tr> <tt> <u> <ul>
  • Snippets of code should be wrapped in <code> tags not <pre> tags. In fact, <pre> tags should generally be avoided. If they must be used, extreme care should be taken to ensure that their contents do not have long lines (<70 chars), in order to prevent horizontal scrolling (and possible janitor intervention).
  • Want more info? How to link or or How to display code and escape characters are good places to start.
Log In?
Username:
Password:

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

How do I use this? | Other CB clients
Other Users?
Others wandering the Monastery: (None)
    As of 2021-10-20 03:11 GMT
    Sections?
    Information?
    Find Nodes?
    Leftovers?
      Voting Booth?
      My first memorable Perl project was:







      Results (78 votes). Check out past polls.

      Notices?