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.
--) 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.
--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
-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.