At my job, we recently started a style guide for our code. One point of order is the documentation we put in our code. We are putting Pod in all our modules, and even some of our CGI programs (that accept an insane number of CGI parameters).

In addition, we are moving towards commenting blocks of code, to increase readability, and to keep everyone on the same level -- just because I wrote the code doesn't mean the guy next to me will never touch it, or maybe even modify it.

But documenting your code line-by-line is not efficient. If you have to do that, you're not using descriptive variable and function names. They have names for a reason -- you can give them names that fit their functionality.

One of the most informative comments I wrote today was an ASCII depiction of two images I was creating with GD. The variable names are helpful, but it's difficult to get a grasp of what the coordinates mean without some graphical representation of the figure:

# draw a skewed rectange for each data-point

#     ____
#    G p  D \
#   / o / | |
#  B_t_C  | | 
# |       | +-- $val_height
# | face  | |
# |       | /
# |       E \ 
# |      /  +-- $slant_height
# A____F/   /
#
# \-+-/ \+/
#   |    |
# $ppd   - $consts{slant}
[download]

And then I went on and used those alphabetic labels when I created the polygons:

if ($params->{dim} == 3) {
  my $face = GD::Polygon->new;
  A: $face->addPt($x_pos, $yi + $val_height - 1);
  B: $face->addPt($x_pos, $yi + $slant_height);
  C: $face->addPt($x_pos + $ppd, $yi + $slant_height);
  D: $face->addPt($x_pos + $ppd + $consts{slant}, $yi);
  E: $face->addPt($x_pos + $ppd + $consts{slant}, $yi + $val_height - 
+$slant_height - 1);  # E
  F: $face->addPt($x_pos + $ppd, $yi + $val_height - 1);
  $image->filledPolygon($face,$hist_front{"@$cRGB"});

  my $top = GD::Polygon->new;
  B: $top->addPt($x_pos, $yi + $slant_height);
  G: $top->addPt($x_pos + $consts{slant}, $yi);
  D: $top->addPt($x_pos + $ppd + $consts{slant}, $yi);
  C: $top->addPt($x_pos + $ppd, $yi + $slant_height);
  $image->filledPolygon($top,$hist_top{"@$cRGB"});
}
[download]

japhy -- Perl and Regex Hacker

---

---

• 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.