Developer Forums | About Us | Site Map


Useful Lists

Web Host
site hosted by netplex

Online Manuals

Road to better programming: Chapter 2. Commenting your code
By Teodor Zlatanov - 2004-02-11 Page:  1 2 3 4 5 6 7 8

Writing POD documentation and help for the program

Plain old documentation (POD) is a way to document a Perl script inside the script itself. The perldoc perlpod command will tell you more about POD documentation and its syntax. Good POD documentation means that users can access help for your program quickly and efficiently. Take the time to learn the POD syntax; writing manuals will be much easier. In addition, POD is compatible with a variety of manual formatters, so you can generate a plain text file, a UNIX-style man page, and a professional-looking LaTeX file from the same documentation. POD is a fairly limited format, but perfectly sufficient for most documentation needs.

Generally, the following sections should be present in POD documentation: NAME, SYNOPSIS, DESCRIPTION, OPTIONS, RETURN VALUE, ERRORS, DIAGNOSTICS, EXAMPLES, ENVIRONMENT, FILES, CAVEATS/WARNINGS, BUGS, RESTRICTIONS, NOTES, SEE ALSO, AUTHORS, HISTORY (from perldoc pod2man, where you can find more information on each section; keep in mind that these are suggestions rather than imperatives).

Some programmers make the -h switch to their programs invoke perldoc on the program, so the POD documentation is printed out as if the user had typed perldoc The problem here is that a user doesn't want too much extra information from the -h switch. He just wants the synopsis and the list of options. Thus, it is better to write separate help handlers arising from the use of the -h switch:

Listing 12

# print_help: help handler, prints out help for and exits
sub print_help
 # print the help itself
 print << EOHIPPUS;
 This is help for the program.

You can pass options to as command-line arguments.  For

..../ -h
..../ -show suspects

List of options:

-h     : print this help

-show  : show the suspects, victims, or detectives (all of them if no
         second argument is specified)

-quiet : print no information other than the killer's name

 exit;                                  # do nothing else, just exit quietly

Note the documentation of print_help itself. Also, the the appearance of the POD documentation and other online help is important. The first place a user goes is not the manual. It's much more convenient to use the -h flag, or look at the POD documentation. Note the alignment of the colons, the spacing between lines, and the overall neatness. Outward appearances do matter, often more than the actual functionality provided by the program. Well-written programs should have good documentation first and foremost.

Some programmers like to include POD documentation in their program instead of regular comments. Such POD comments begin with =pod on a line by itself (there are other options, explained in the perlpod documentation), and end with =cut on a line by itself. The =pod line tells the Perl compiler to stop interpreting everything until the =cut line, in effect excluding that block of text from the script itself. This is fine if your users are also programmers, but may confuse normal users who just want to look at the documentation for the script, not the comments for the code itself. This approach also scatters documentation throughout the code. Use it with restraint.

View Road to better programming: Chapter 2. Commenting your code Discussion

Page:  1 2 3 4 5 6 7 8 Next Page: Resources

First published by IBM developerWorks

Copyright 2004-2024 All rights reserved.
Article copyright and all rights retained by the author.