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

comment on

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

I have my doubts about this style too :-)

#--------------------------------------------------------- # Function:   get_records (taken from process_member.pl) # Arguments:  DB handle #             sql query string # Returns:    result array of SQL query #--------------------------------------------------------- sub get_records {    my ( $db_handle_ref, $sql ) = @_;    my @recs; # [...]    return @recs; }

Several issues:

First off, as several other people have pointed out, if this is documentation aimed at the users of the code then POD would be the preferred format. That way you get the support of a lot of POD:: modules for formatting and reading your documentation.

Second, look at what the comments tell you - or rather what they don't:

# Function:   get_records (taken from process_member.pl)

The function name and the filename it lives in. Both of which we already know (we're looking at the file to see the comment, and the subroutine name is part of the subroutines declaration.)

# Arguments:  DB handle #             sql query string

The arguments are a database handle (to what?) and an SQL query string (of what format?). This gives us no more information that we would get from the first line of the function:

   my ( $db_handle_ref, $sql ) = @_;

It would be even easier if we called the database handle $dbh which would be familiar to all users of DBI, and a more descriptive name for the sql query.

Finally this:

# Returns:    result array of SQL query

Tells us, I think, that we get an array of the rows returned by the SQL query. This is:

  • Phrased badly. I could read that as an array of SQL query objects rather than the results from the SQL query.
  • It doesn't tell me what array consists of. Is it an array of hashes keyed of column names? An array of values in order? What?

All of this information is better expressed in the code itself. Rather than spending time writing comments that can easily get out of sync with the code, spend time writing clear expressive code. If you can't look at a subroutine and understand what it does rewrite it until you do. Break it into smaller subroutines, use better subroutine names, use better variable names, etc.

For example the original routine might be better expressed as (guessing it's actual use since the comment doesn't actually say :-)

sub fetch_matching_process_records {    my ( $dbh, $sql_query ) = @_;    my @process_records; # Something that populates @process_records with # ProcessRecord objects with a known API    return @process_records; }

In reply to Re: flower box comments by adrianh
in thread flower box comments by mandog

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 making s'mores by the fire in the courtyard of the Monastery: (5)
    As of 2019-09-23 18:11 GMT
    Sections?
    Information?
    Find Nodes?
    Leftovers?
      Voting Booth?
      The room is dark, and your next move is ...












      Results (282 votes). Check out past polls.

      Notices?