Using shell/bash commands in code? Use "long" options

#bash #shell

Many developers at one point or another need to use a bash or shell script inside code.

Maybe it's a command being issued in Docker, or an exec function in Node.js, or perhaps a shell command in a Jenkins pipeline.

One short and simple tip though I've picked up after having to do this a few times is, when documenting commands in code, always use the long options when available.

Long (--) and short (-) options are there for good reason -- one for clarity in documentation, the other for brevity when typing out commands in the terminal.

For example, here's a sample docker command below. Imagine you found this in code:

docker build --no-cache -t myimage:latest -f path/Dockerfile -q .

Let's say you were new to docker and encountered this in a Jenkinsfile or bash script.

The --no-cache seems quite clear about what it does. But what about the rest?

Wouldn't it have been better if this had been how it was written:

docker build --no-cache --tag myimage:latest --file path/Dockerfile --quiet .

Even better yet, what if it had been broken into a longer statement, using line breaks for each option?

docker build \
    --no-cache \
    --tag myimage:latest \
    --file path/Dockerfile \
    --quiet \
    .

Now the next person who reaches this code is less likely to have the urge to look up what -q, -f, and -t is for.

Not all terminal applications are consistent with what their short options mean, it can be easy to mix them up. It is often the case that things like -q will mean --quiet in one application, and --query in another.

Do this, and your code reviewers and inheritors may very well thank you for it.