Beefy Boxes and Bandwidth Generously Provided by pair Networks
Welcome to the Monastery

comment on

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

Excellent feedback so far. The only thing I'd add is to lose the comments.

Let the code (ie. the proper naming of variables and function names) do the saying of what is happening. Comments should only be used to describe *why* something is happening. A comment in code should be a rather rare occurrence. If I see a comment in code, it's to point out why the following code is doing something that goes against the norm.

For example:

### execute command ### get the data $dbHandle=$db->prepare($dbCommand); $dbHandle->execute(); my $data = $dbHandle->fetchall_arrayref();

It's readily apparent that execute() and fetchall_arrayref() are performing the "execute command" and "get the data".

I know it's instinctive when first writing code to pepper it with comments, but trust me, if you practice without them, you'll become more efficient as a code reader and writer more quickly. It will force you to come up with more descriptive names for various items within your code.


my $var1 = 0; my $var2 = 1; # Draw an axis with a pencil and a ruler function($var1, $var2);


my $pencil = 0; my $ruler = 0; draw_axis($pencil, $ruler); sub draw_axis { my ($pencil, $ruler) = @_; if (! $pencil) { # On rare occasions, a pencil might be broken, so do this $pencil++; } }

  • 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 How to display code and escape characters are good places to start.
Log In?

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

How do I use this? | Other CB clients
Other Users?
Others scrutinizing the Monastery: (5)
As of 2023-06-10 22:27 GMT
Find Nodes?
    Voting Booth?
    How often do you go to conferences?

    Results (39 votes). Check out past polls.