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.

  1. Unless you add a layer or an alias to your software-sandwich. ↩︎

  2. “By the way, I have this git uncommit alias that performs all of the commands I need to remove the last commit but keep the changes in my working tree.” ↩︎