Mathieu Larose

Write Readable Commands with Long Options

May 2024

Many commands offer two ways to specify options: short flags (like -v) and longer, descriptive options (like --verbose). While short flags are convenient for quick use in interactive shells, they lack clarity in code and documentation.

Consider the following yarn workspaces foreach command:

$ yarn workspaces foreach -Apt run build

Compare it to the same command using long options:

$ yarn workspaces foreach --all --parallel --topological run build

The second version is clearly more readable. By using long options, you make the command self-explanatory, which simplifies maintenance and debugging. Even if you're not familiar with yarn workspaces foreach, the long options give you a clearer understanding of what the command does. And that may be sufficient for you to continue reading the script you are debugging, instead of forcing you to stop and look up the short flags online.

Short options are convenient for quick, one-off commands in an interactive shell. However, for code and documentation, long options are preferred because they improve clarity.

Like this article? Get notified of new ones: