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

---

---

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! —

• How do I compose an effective node title?
• How do I post a question effectively?
• Markup in the Monastery

Posts may use any of the Perl Monks Approved HTML tags:

a, abbr, b, big, blockquote, br, caption, center, col, colgroup, dd, del, details, 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, summary, 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:
	&		&
	<		&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.