Avoid command abbreviations
Whenever possible, I avoid using abbreviated forms of commands and commandline flags. I see them all the time in readmes, in blog posts, in pairing sessions. When I do not know what is being abbreviated: I can miss the author’s point, and I can get distracted in my attempt to follow along. Custom command aliases also function as abbreviations, and I often feel the same way about them.
With NPM, install is often shortened to i:
npm i glob@^14.0.0
Anyone with experience using package managers can adapt to this shortform
version. Meanwhile, someone just learning, who doesn’t know what a package
manager is, or what glob@ could mean, or what npm is, may need a few
moments to think through it, or a lot of expository information about the
purpose of this command. Writing out install instead of i is remarkably
helpful for the someone just learning.
Git has many unholy subcommands, none of which can be abbreviated.1 Its commandline flags, though, are often abbreviated:
git checkout -p -- spec/
Even experienced Git users may have never used the -p flag before.
Writing out --patch can give a hint to
those people about what’s going to happen. Meanwhile, someone just learning
has a lot more reading to do. Maybe they’ve used a git checkout command
before, but git-checkout does lots of stuff they might not
expect. -p versus --patch doesn’t add immediate
value for the someone just learning, but --patch is
less ambiguous, easier to grep in doc pages, and easier to search for online.
I’ll go further: there’s never a reason to commit shortform commandline flags or arguments to a script. Doing so hampers the readability for anyone less familiar with the command. It even hampers readability for the author’s future self, unless they’re using this command all the time. Take this Guix shell command, for example:
guix shell \
-C \
-F \
-N \
-E "^DISPLAY$" \
-E "^XAUTHORITY%" \
-m manifest.csm \
--expose="^XAUTHORITY" \
--expose=/tmp/.X11-unix \
--expose=/dev/dri \
lib xcb libxkbcommon mesa vulkan-loader xauth -- ./my-app
Even someone who knows what Guix is and what guix shell does
might not guess what all of -C, -F, -N, -E, and -m do. And seeing
an --expose argument next to an -E argument
with similar values might mislead them into thinking these things are
equivalent. (They’re not.) Using the longform commandline flags makes this
command easier to understand at a glance, and it may even save someone from
a trip to the manual:
guix shell \
--container \
--emulate-fhs \
--network \
--preserve="^DISPLAY$" \
--preserve="^XAUTHORITY%" \
--expose="^XAUTHORITY" \
--expose=/tmp/.X11-unix \
--expose=/dev/dri \
--manifest=manifest.csm \
lib xcb libxkbcommon mesa vulkan-loader xauth -- ./my-app
Custom command aliases are often used to abbreviate, as well. Most users use
them to reduce typing (i.e. g for git; bx for bundle exec) or to string
multiple successive commands into a single shortform command. So, it’s easy
to understand how aliases communicate intent poorly.
Take my Git alias, git uncommit. An experienced Git user might guess what
my uncommit alias does under the hood, but I would hate to communicate to
someone just learning that Git provides a comprehensive uncommit action that
everyone everywhere uses. Worse, my uncommit alias may behave differently
than someone else’s. In writing, it’s clearer to just type out what I mean:
git reset --soft HEAD~1
git reset .
Most of the time, it would add undue complexity for me to use my git uncommit
alias in writing. (It’s usually beside the point to explain what some utility
alias does.) In a pairing session, I would consider using the alias after
giving verbal context.2 But if I’m pairing with someone just learning
Git, there is no value in using the alias unless we want to learn about Git
command aliases together.
I hope you’ll join me in choosing to sparingly use these command and commandline abbreviations in writing, and to never use aliased commands in writing unless you have a compelling reason to.