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.
Top comments (1)
Yes! this is one of the rules in my team. Long options in scripts (mandatory), for the CLI they are optional.