Results tagged “how to” from Mechanix

On the perl-qa list tonight, we were discussing how best to find all the modules used in a source tree. To do the job right, you'd have to run the code and then look at the %INC:: hash, which shows the paths of all modules loaded. The low-tech and usually-good-enough solutions we came up with use ack:

$ ack -h '^use\s+(\w+(?:::\w+)*).*' --output=\$1 | sort -u

Thanks to Andy Armstrong for coming up with a better regex than mine, which assumed that the use statement would necessarily end with a semicolon.

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