Recently in Documentation Category

Google's main search screen now returns code snippets in its list of results. This is not just in code.google.com any more.

I needed to find the docs for the PHP function ftp_connect, so searched Google for it. (I could have gone to php.net and searched there, but why?) The list of results has three hits to PHP manual pages, and the fourth and fifth are bits of code that use ftp_connect. Anyone know if they're getting Perl stuff in there as well? I tried it with WWW::Mechanize, but couldn't turn up hits.

I have one rule to documenting code:

  1. Why, not what: Explain why the code is doing what it's doing, not what it is doing.

Clearly this doesn't apply to code that is an API of some kind, where the code is the interface. Everywhere else, though, where the code is a mechanism to get the front-facing work done, explain the decisions that went into making the code do what it is.

Some hypothetical examples:

# Use port 3000 instead of 80 because that's what 
# Corporate is allowing us to use through the firewall.

# Force this column to be a bigger font for Stan in Accounting.

# Use Imager instead of Image::Magick because of
# incompatibilities with frongdoodle mode in PNG images.

# Can't use a JOIN here because MySQL 5.0's optmizer
# makes a bad plan.  This is supposed to get fixed in 5.1.  See 
# http://wiki.mycompany/MySQL_optimization_problems for the details

Note how all these examples explain something that may be out of the ordinary, or make the next reader (maybe even you) think "What the hell was this guy thinking?" A well-placed, well-written, well-thought-out comment will make the reader say "Aaaah, THAT'S why it's like that!"

About this Archive

This page is a archive of recent entries in the Documentation category.

Databases is the previous category.

Modules is the next category.

Find recent content on the main index or look in the archives to find all content.

Other Perl Sites

Other Swell Blogs

  • geek2geek: An ongoing analysis of how geeks communicate, how we fail and how to fix it.