Summary

According to Oualline’s law of documentation, 90 percent of the time, the documentation is lost. Out of the remaining 10 percent, 9 percent of the time it will be a version or two out of date and therefore completely useless. The 1 percent of the time that you have the documentation and the correct version of the documentation, it will be written in Japanese (my Japanese readers might want to substitute the term “English” here).

Perl has beaten the odds and created a standard way of documenting your programs. By keeping the documentation inside the program, things do not get lost.

One strength of the Perl CPAN archive is that almost all the modules are documented. That means that not only are they useful, but also you have the documentation so that you can use them.

One final note: Far too many programmers skip the documentation step or put it off until tomorrow. The results are undocumented Perl programs. Perl is not the most readable language in the world, so an undocumented program quickly becomes obsolete.

Always document your programs. Even if you are writing the program only for yourself, document it for practice. The more you write, the easier it is, and the better you’ll become at it. Remember, your program is not finished until you tell people how to use it.