A large part of making interfaces consistent is being consistent in the way individual components of those interfaces are specified. Some conventions that may help to design consistent and predictable interfaces include:
Require a flag preceding every piece of command-line data, except filenames
The arguments advanced in Chapter 9 against passing subroutine arguments positionally apply equally well to entire applications. Users don't want to have to remember that your application requires "input file, output file, block size, operation, fallback strategy"...and requires them in that precise order:
> lustrate sample_data proc_data 1000 normalize log
They want to be able to say explicitly what they mean, in any order that suits them:
> lustrate sample_data proc_data -op=normalize -b1000 --fallback=log
Provide a flag for each filename, too, especially when a program can be given files for different purposes
Users might also not want to remember the order of the two positional filenames, so let them label those arguments as well, and specify them in whatever order they prefer:
> lustrate -i sample_data -op normalize -b1000 --fallback log -o proc_data
Use a single - prefix for short-form flags, up to three letters (-v, -i, -rw, -in, -out)
Short-form flags are appreciated by experienced users, as a way of reducing typing and limiting command-line clutter. So don't make them type two dashes in these shortcuts.
Use a double -- prefix for longer flags (--verbose, --interactive, --readwrite, --input, --output)
Flags that are complete words improve the readability of a command line (in a shell script, for example). The double dash also helps to distinguish between the longer flag name and any nearby file names.
If a flag expects an associated value, allow an optional = between the flag and the value
Some people prefer to visually associate a value with its preceding flag:
> lustrate -i=sample_data -op=normalize -b=1000 --fallback=log -o=proc_data
Others don't:
> lustrate -i sample_data -op normalize -b1000 --fallback log -o proc_data
Still others want it both ways:
> lustrate -i sample_data -o proc_data -op=normalize -b=1000 --fallback=log
Let the user choose.
Allow single-letter options to be "bundled" after a single dash
It's irritating to have to type repeated dashes for a series of flags:
> lustrate -i sample_data -v -l -x
So allow experienced users to also write:
> lustrate -i sample_data -vlx
Provide a multiletter version of every single-letter flag
Short-form flags may be appreciated by experienced users, but they can be troublesome for new users: hard to remember and even harder to recognize. Don't force people to do either. Give them a verbose alternative to every concise flagfull words that are easier to remember, and also more self-documenting in shell scripts.
Always allow - as a special filename
A widely used convention is that a dash (-) where an input file is expected means "read from standard input", and a dash where an output file is expected means "write to standard output".
Always allow as a file list marker
Another widely used convention is that the appearance of a double-dash () on the command line marks the end of any flagged options, and indicates that the remaining arguments are a list of filenames, even if some of them look like flags.
