14.1. Command-Line Structure
Command-line interfaces have a strong tendency to grow over time, accreting new options as features are added to the application. Unfortunately, the evolution of such interfaces is rarely designed, managed, or controlled, so the set of flags, options, and arguments that a given application accepts are likely to be ad hoc and unique.
This also means they're likely to be inconsistent with the unique, ad hoc sets of flags, options, and arguments that other related applications provide. The result is inevitably a suite of programs, each of which is driven in a distinct and idiosyncratic way. For example:
> orchestrate source.txt -to interim.orc > remonstrate +interim.rem -interim.orc > fenestrate --src=interim.rem --dest=final.wdw Invalid input format > fenestrate --help Unknown option: --help. Type 'fenestrate -hmo' for help
Here, the orchestrate utility expects its input file as its first argument, while its output file is specified using the -to flag. But the related remonstrate tool uses -infile and +outfile options instead, with the output file coming first. And the fenestrate program seems to require GNU-style "long options": src=infile and dest=outfile. Except, apparently, for its oddly named help flag. All in all, it's a mess.
When you're providing a suite of programs, all of them should appear to work the same way, using the same flags and options for the same features across all applications. This enables your users to take advantage of existing knowledge[*] instead of asking you.
Those three programs should work like this:
> orchestrate -i source.txt -o dest.orc > remonstrate -i source.orc -o dest.rem > fenestrate -i source.rem -o dest.wdw Input file ('source.rem') not a valid Remora file (type "fenestrate --help" for help) > fenestrate --help fenestrate - convert Remora .rem files to Windows .wdw format Usage: fenestrate [-i <infile>] [-o <outfile>] [-cstq] [-h|-v] Options: -i <infile> Specify input source [default: STDIN] -o <outfile> Specify output destination [default: STDOUT] -c Attempt to produce a more compact representation -h Use horizontal (landscape) layout -v Use vertical (portrait) layout -s Be strict regarding input -t Be extra tolerant regarding input -q Run silent --version Print version information --usage Print the usage line of this summary --help Print this summary --man Print the complete manpage
Here, every application that takes input and output files uses the same two flags to do so. So a user who wants to use the substrate utility (to convert that final .wdw file to a subroutine) is likely to be able to guess correctly the required syntax:
> substrate -i dest.wdw -o dest.sub
And, anyone who can't guess that probably can guess that:
> substrate --help
is likely to render aid and comfort.