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