Perl Best Practices

14.3. Meta-options

Standardize your meta-options.

Meta-options are those command-line flags that tell the user how to use the application, rather than telling the application how to behave. They're the "What are my options?" options.

Every program you write should provide (at least) four of these, all of which print to standard output and then terminate the program immediately. Those four meta-options are:

usage

This option should print a concise usage line.

help

This option should print the usage line, followed by a one-line summary of each available option.

version

This option should print the program's version number.

man

This option^[*] should print the complete documentation for the program, paging it out if necessary.

^[*] The flag ought to have been single-dashed (-man) under the "Command-Line Conventions" guidelines, but the double dash is used instead, to keep all four meta-options structurally consistent.

Note that the names of the four options are not negotiable. That's what "standardized" means.

And, yes, those standardized names are much longer than -u, -h, -v, and -m. That's also intentional. Meta-options should need to be called only relatively infrequently, especially if your other options have been designed carefully and consistently, so they're easy to remember. And, because they'll be infrequent choices, meta-options ought to have longer invocations, leaving the shorter names available for things that users type all the time.

For example, -h and -v are far more useful as flags to specify horizontality or verticality, or height and velocity, or hairiness and verbosity. But if all your applications already use them to summon help and version information, you'll be stuck with -hor/-ver, or -hgt/-vel, or -hair/-verb.

Don't make up other names for these standard flags^[*]. For example, using -hmo as the "help me, Obi-Wan" flag is cute. For about five seconds. After which, it becomes just another counter-intuitive, hard-to-remember, have-to-look-it-up-every-time obstacle to the user.

^[*] Not unless you have the clout to make your choices the universal standards throughout your project. And your entire client base.