Section 14.1. Command-Line Structure

14.1. Command-Line Structure

Enforce a single consistent 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.

^[*] Or, as your pointy-haired boss would prefer you to say: " ... proactively maximizes quality client-level cross-semantic uptake synergies by leveraging in-house cognitive investment transfer from pre-assimilated complexity-enabled environments".

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.