Forem: Thibaut Rousseau

TDD is a personal practice

Thibaut Rousseau — Mon, 18 Dec 2023 16:12:19 +0000

I know TDD. I know what real TDD is. I know how to do it right, whatever that means depending on the TDD practitioner.
I still don’t like this practice, and rarely use it, except in 2 situations:

I’m fixing a bug in an existing code base: in this case I’ll write a test first to reproduce and isolate the bug, and then fix it and refactor if needed
I’m adding a new use case to an existing feature, and will treat the lack of existence of this new case as a bug, see 1.

I don’t ever, ever, EVER use TDD to write new features from scratch. It doesn’t work for me. It doesn’t match my mental model. It doesn’t help me go faster, doesn’t make me produce better code, and doesn’t make me write more, or more useful tests. I don't enjoy it and it doesn't provide me with any kind of satisfaction.

I still have a personal methodology, but it’s not TDD. I still strive to write good test and maintain good coverage, but not doing TDD.

TDD should not be forced upon developers who don’t want to follow it, in the same way a specific IDE should not be forced upon a developer. TDD is a tool, not a goal in itself. The shared goal is to have a well tested code base that is as safe as possible from regressions. How developers achieve that doesn’t matter.

TDD should not be conflated as "writing tests". I often see the rhetoric that, if you don’t do TDD, then you don’t write tests. If I showed you a code base with tests, there would be no way for you to know if they’ve been written in TDD or not.

TDD is not a team practice. Writing tests is a team practice. Code review is a team practice. Automated CI is a team practice. Whether a developer does or does not do TDD has no impact on the rest of the team. I could tell you I'm doing TDD if it pleases you, and you'd have no way to know that I don't, micro-managing set aside.

If in TDD you trust, don’t proselytize it. TDD is a personal practice.

Shell aliases on steroids

Thibaut Rousseau — Thu, 10 Feb 2022 20:31:56 +0000

Aliases, whether you use Bash, ZSH or any other shell, are a really easy way to improve your day to day workflow. The basic syntax for aliases is the following:

alias l='ls -al'

This syntax is pretty simple, but is unfortunately very limited in what you can do:

it doesn't let you handle custom parameters. What if you want to add a custom --json parameter to curl that expands to --header "Content-Type: application/json"?
it doesn't let you add subcommands. What if you want to create a custom docker sh subcommand that expands to docker exec -it container_name sh?

Well the cool thing is that you can do all of that, simply using shell functions! Yep, nothing new in here, but using functions to create advanced aliases is often disregarded or forgotten.

Anyway, let's see how to implement the above aliases!

Note: The following snippets will use Bash specifically. It should not be too hard to adapt them to other shells.

Add a custom flag to a command

When using curl, I often want to send JSON payloads. To do so, the Content-Type: application/json header is usually required by servers. I'd like to be able to write this:

curl --json -d '{"foo": "bar"}' https://example.com/endpoint

instead of this:

curl -H 'Content-Type: application/json' -d '{"foo": "bar"}' https://example.com/endpoint

You can add this custom flag with the following function:

curl() {
  local -a args;
  for arg in "$@"; do
    case $arg in
    --json) args+=("-H" "Content-Type: application/json") ;;
    *) args+=("$arg") ;;
    esac
  done
  command curl "${args[@]}"
}

So what happens in this snippet?

At first, we create a new curl function. It will wrap the already existing curl command and we'll be able to modify how it's called.
Then, we loop on all the arguments passed to the command, and add them to a new args array.
When we encounter the --json argument, we push the new arguments "-H" "Content-Type: application/json" to our list instead.
Finally, we call the original curl command with the modified list of arguments. Make sure to use command in front of curl to avoid calling the alias function recursively.

And that's it! There's no magic in here, we just cleverly use some basic Bash building blocks.

Using the same techniques, we can easily decide to replace the -d argument with --json to get the following final command:

curl --json '{"foo": "bar"}' https://example.com/endpoint

This is left as an exercise to the reader.

Add a custom subcommand to a command

When using docker, it's common to get into a container to explore the file hierarchy. The command to do this operation is the following:

docker exec -it container_name sh

I want to write this instead:

docker sh container_name

The principle is the same as above, you can write a function like this:

docker() {
  if [ $# -ge 1 ]; then
    case "$1" in
      "sh")
        if [ $# -ne 2 ]; then
          echo '"docker sh" requires 1 argument.'
          echo
          echo "Usage:  docker sh NAME|ID"
          echo
          echo "Start an interactive shell inside a running container"
          return 1
        fi
        command docker exec -it "$2" bash
        ;;
    esac
  fi
  command docker "$@"
}

The only difference with the previous script is that we create a new sh subcommand that we implement ourselves.
We could trivially implement additional flags (--help, --bash, etc.) to our new subcommand following the same patterns.

This article contains no novel concepts, but will helpfully help you get creative in creating more specific aliases to your workflows.

The main thing to remember is the existence of the command built-in that allows you to declare a function with the same name as an existing command, and still be able to use the original command.

Learn to use screen, a terminal multiplexer

Thibaut Rousseau — Mon, 25 Sep 2017 20:04:23 +0000

screen, or GNU screen, is a terminal multiplexer. It allows to manage multiple terminal sessions within the same console. In a way, it does the same thing as modern terminal emulators such as Terminator or Terminology with their built-in tab system and layout management. The main benefit is that screen also works through an SSH connection: you will be able to use your screen knowledge and configuration on any machine supporting screen in the world!

screen has been around for almost 30 years so it's pretty stable now. It is released under the GPL license.

The main issue I had when starting with screen was its relative difficulty when compared to simple terminal emulators. So I will make a tour of the most useful keyboard shortcuts for a practical use, and share with you my screen config. You can also jump directly to the cheatsheet if you want.

Basic usage

screen is not installed by default, so you need to install it first using your package manager.

To start screen, open a terminal and run the command screen. Not that hard, is it?

We're ready to start learning screen. Don't worry, that's only a few commands!

Window managements

Now you have opened screen, the first thing you need to know is how to create a new "window" (i.e. a new virtual terminal). To do so, press the keys Ctrl+a, and then press c. The screen shortcuts all consist of Ctrl+a (called "escape key" or "prefix") followed by another key. You now have two windows opened running in parallel, you can have vim in the first one, and a bash in the second one for example, and that's what screen is all about.

You can visualize all the opened windows with Ctrl+a ". This view allows you to navigate through your windows with the arrow keys, the 0-9 numbers and the enter key. This command is great because it gives you a global overview of your current session, I used it a lot at first.

But there are more ways to navigate through the windows! I personally use almost exclusively the commands Ctrl+a p (previous window) and Ctrl + a n (next window). These shortcuts require to have your windows in mind though, but it comes with practice. And don't forget Ctrl+a " is here to rescue you in case of doubt. ;)

It's also possible to jump to another window with the command Ctrl+a number, where number is a number between 0 and 9. This matches the "Num" column of the Ctrl+a " view.

Finally, you can kill a window when you have no use for it anymore. To do so, just press Ctrl+d in the shell. There's also a screen command with the "same" effect but it's usually better to proceed this way. Note if you kill all the windows of a session, the session terminates.

Summary:

Ctrl+a c to create a new window
Ctrl+a " to visualize the opened windows
Ctrl+a p and Ctrl+a n to switch with the previous/next window
Ctrl+a number to switch to the window number
Ctrl+d to kill a window

Session management

Now you can manage your windows, it is time you learn how to manage your screen sessions.

You just learned you can terminate a session by killing all its windows, that's a good start. We will now see how to exit a session without killing it. It means you'll be able to manage multiple persistent sessions in parallel. This is called "detaching" a session. To be clear, a detached session is a session which is still active in background, but on which no one is connected. An attached session is a session which is active and currently used.

The first thing I'll ask you to do is to kill your current screen session if you haven't done it already. You can then list all your screen sessions by running the command screen -ls. If all your sessions are closed, it should print something like:

No Sockets found in /var/run/screen/S-thiht.

Now, we'll start a new session, but we'll give it a name so that we can come back to it more easily later. Run the command screen -S my_session. If you run the command screen -ls, you should obtain something like:

There is a screen on:
    10321.my_session        (Attached)
1 Socket in /var/run/screen/S-thiht.

Since you're connected to the session, it's presented as attached.

Now you're connected to a session named "my_session", you can detach it from the current terminal with the command Ctrl+a d. This should result in a message like:

[detached from 10321.my_session]

As usual, you can list the currently running sessions with screen -ls. This time, "my_session" should be listed as detached:

There is a screen on:
    10321.my_session        (Detached)
1 Socket in /var/run/screen/S-thiht.

I suggest you start and detach a few screen sessions to understand how it works. Be careful not to use the same session name twice, screen allows it but it can be more painful to resume a session if there are name conflicts.

With multiple screen sessions, the screen -ls gives something like:

There are screens on:
    10474.downloads (Detached)
    10427.work      (Detached)
    10321.my_session        (Detached)
3 Sockets in /var/run/screen/S-thiht.

If there aren't any conflicts, you can resume a session simply with the command screen -x session_name. So for example if you run screen -x my_session, your session "my_session" will be resumed with the windows you opened before! And if you run screen -ls, it should appear as attached:

There are screens on:
    10474.downloads (Detached)
    10427.work      (Detached)
    10321.my_session        (Attached)
3 Sockets in /var/run/screen/S-thiht.

A last useful thing you should know is how to kill a detached session without connecting to it. To do so, the command to run is a bit tricky: screen -S session_name -X quit. This means you pass the command "quit" to the session named "session_name". It's a bit hard to remember so I generally simply resume my session and kill all its windows one by one.

Summary:

screen -ls to list the sessions and their status
screen -S session_name to start a session with a given name. The name should be unique
Ctrl+a d to detach a session
screen -x session_name to resume (reattach) a session knowing its name
screen -S session_name -X quit to terminate a detached session

Advanced usage

The hardest part is over! You have discovered screen and you know how to use it. All you need now is practice.

In this section, I'll present a few interesting features of screen, but they're definitely not necessary to use it, so feel free to come back and read this part later.

Layout management

In the introduction, I talked about how Terminator and Terminology can work as layout managers. The good news is screen also permits to do that. So to split horizontally, you can use the command Ctrl+a S, and to split vertically you can use Ctrl+a |.

To switch to the next region (this is how the split panes are called), the command to use is Ctrl+a <Tab>. Each region behaves normally: you can run any command you have learned so far.

To close the current region, use Ctrl+a X. If you work with a lot of panes, you can close them all but the current one with Ctrl+a Q.

Summary:

Ctrl+a S to split horizontally
Ctrl+a | to split vertically
Ctrl+a <Tab> to switch to the next region
Ctrl+a X to close the current region
Ctrl+a Q to close all the regions but the current one

Work with the buffer

To follow, I'll talk about an important feature of screen: the copy mode, or scrollback mode.

To enter the copy mode, the command is either Ctrl+a <Esc> or Ctrl+a [, choose your side. The copy mode allows you to navigate through the console buffer without using your mouse. Since you can't use your wheel to scroll by default, this is the normal way to go back in the results. This mode lets you use some vim commands for the movements (arrow keys, 0, $, g, G, etc.).

You can copy some text (that's what the mode is for!) by marking the beginning and the end of a section with the space bar. You can then paste it with Ctrl+a ]. For more informations, check the man screen and look for "copy".

Summary:

Ctrl+a <Esc> or Ctrl+a [ to enter in copy mode
<Space> to select and copy some text in copy mode
Ctrl+a ] to paste the content of the buffer

Session sharing

I'll finish with a last screen feature I want you to know about: it allows to share a session between multiple users. When working on a remote server, this comes really handy.

So first, you have to start a session as usual. Then, we'll use the command mode of screen to enable the multiuser mode and give the access right to some users. To enter the command mode, type Ctrl+a :. You can then enable the multiuser mode with the command multiuser on.

Then to add a specific user to the session, enter the command mode again with Ctrl+a : and type the command acladd username (ACL stands for "Access Control List") with the name of the user you want to add instead of username.

The user username is now able to join your session simply with the command screen -x your_username/session_name. The session is completely shared, which means you can see what the other users do in real time and so can they.

When a session is shared with multiple users, it can be nice to know who is currently connected on it. You can have this info and more thanks to the command Ctrl+a *. The view shows a few useful informations, namely the window a user is currently using, or their permissions.

Finally, you can revoke the access rights of user with the command acldel username in command mode. There's more you can do to manage a shared session, but I won't go into details, the man page covers everything. Now you have a basic understanding of screen, it should be easier to understand.

Summary:

Ctrl+a : to switch to command mode
- "multiuser on" to enable the multiuser mode
- "acladd username" to give the access rights to the user username
- "acldel username" to remove the access rights to the user username
screen -x owner/session_name to join a session started by another user
Ctrl+a * to list the other connections to a session

Practical tips

Automatically list the screen sessions

When I start my terminal, I like it to list the current screen sessions. To do so, I simply added the screen -ls command to my .bashrc. So now whenever I open a terminal, I'm welcomed with my screen status:

There are screens on:
    2927.my_screen3 (Attached)
    2882.my_screen2 (Attached)
    2840.my_screen1 (Detached)
3 Sockets in /var/run/screen/S-thiht.

Not only is it really useful to have this status without asking for it, but it is also a good way to think about always using screen.

Good aliases

As you're now aware, screen uses a lot of options. I tried to keep only the most useful in this article but they're still a pain to remember. A good way to remember them is to use aliases. I personally use the following:

alias sn='screen -S'  # sn for screen new
alias sl='screen -ls' # sl for screen list
alias sr='screen -x'  # sr for screen resume
function sk() {
  # sk for screen kill
  # function instead of alias because the order of the parameters matters
  screen -S "$1" -X quit
}

These aliases don't conflict with anything standard and they're really easier to remember and to type, so I strongly advise you to use them!

Custom configuration

screen can be customized in various ways through a .screenrc file, located in your home folder. One of the most useful tricks is the status bar.

I won't go through the configuration of screen in details (you can read man screen or other articles to learn more), but simply share my commented .screenrc with you:

# enable the altscreen
# for example in vim, it allows to scroll with the mouse without
# "overflowing" on the terminal
# also it doesn't "pollute" the terminal when you quit vim
altscreen on

# automatically detach the session if the terminal is closed
autodetach on

# larger command history
defscrollback 10000

# set the encoding of the windows to utf-8
defutf8 on

# disable the startup message
startup_message off

# allow to scroll
termcapinfo xterm* ti@:te@

# disable the annoying visual bell
vbell off

# status bar
# %{= wk}: set the color to white on black
# %S: screen session name
# %-w: previous windows
# %{= kw}: set the color to black on white
# %n: current window number
# %t: current window title
# %{= wk}: set the color to white on black
# %+w: next windows
caption always "%{= wk}%S: %-w%{= kw}%n %t%{= wk}%+w"

Note you can enable any of these options directly from screen's command mode.

Cheatsheet of the main commands

Basic usage

Command	Description
`screen`	Start a session
`screen -ls`	List the sessions and their status
`screen -S session_name`	Start a session named "session_name"
`screen -x session_name`	Resume the session named "session_name"
`screen -S session_name -X quit`	Terminate the session named "session_name"

Command	Description
`Ctrl+a` `c`	Create a new window
`Ctrl+a` `k`	Kill the current window (`Ctrl+d` does the same thing)
`Ctrl+a` `"`	List the opened windows
`Ctrl+a` `p`/`n`	Go to the previous/next window
`Ctrl+a` `0`-`9`	Go to the window n
`Ctrl+a` `d`	Detach the screen session
`Ctrl+a` `:`	Enter the command mode

Split mode

Command	Action
`Ctrl+a` `S`	Split horizontally
`Ctrl+a` `â˜`	Split vertically
`Ctrl+a` `<Tab>`	Go to the next region
`Ctrl+a` `X`	Close the current region
`Ctrl+a` `Q`	Close all the regions but the current one

Copy mode

Command	Action
`Ctrl+a` `<Esc>`/`[`	Enter the copy mode
`<Space>`	Mark a selection
`Ctrl+a` `]`	Paste the content of the buffer

Shared session

Command	Action
`Ctrl+a` `:` `multiuser on`	Enable the multiuser mode
`Ctrl+a` `:` `acladd username`	Give the access rights to username
`Ctrl+a` `:` `acldel username`	Revoke the access rights to username
`Ctrl+a` `*`	List the other connections to the session
`screen -x owner/session_name`	Join a session started by another user

Conclusion

screen is a powerful tool if you use the terminal a lot. Yet, it has some drawbacks, that can be pretty annoying. To list a few you will be confronted to if you really try to use it:

bad UTF-8 support. There are a few configurations to make screen work fine with unicode, but it's still a bit messy. I am not even sure there is a proper way to handle UTF-8 characters in the status bar...
insane status bar configuration. You can see it in the .screenrc I provided, crafting a neat status bar is really hard. It's a shame given how useful they are!

Good news though, all these issues are allegedly solved with tmux, another more recent terminal mutiplexer. I've only used it as a replacement of screen for a few days so I will wait a bit before reviewing it, but it's very similar to screen in its usage, and I'm very satisfied with it so far.

Shell Scripts Matter

Thibaut Rousseau — Sun, 12 Mar 2017 22:57:11 +0000

The shell is an odd beast. Although it goes against every current trend in software engineering (strong typing, compile checks over runtime checks, ...), shell scripts are here to stay, and still constitute an important part of every developer's life.

The weird thing about shell scripts is that even strong advocates of good practices gladly forget all they know when it comes to shell scripting.

Versioning? Why bother, it's disposable code.

Code quality? That's just a shell script, it's garbage anyway.

Testing? Nah. There aren't any decent tools for that.

Wrong, wrong, and wrong. Shell scripts have value. Everything you do for real code should be done for non trivial shell scripts, even for a one-time script. That includes versioning, code reviews, continuous integration, static code analysis, and testing.

Here is a summary of everything that can, and should be done when writing shell scripts.

Note: This article will use Bash as a reference shell. Most of the content can be transposed to other POSIX compliant shells.

Keep your scripts in version control

Keeping shell scripts under version control has multiple advantages:

It constitutes a library. Shell scripts can be hard to write. If there's a reference for something difficult somewhere, your coworkers will thank you when they need it. You should setup a "shell-scripts" repository somewhere as soon as possible.
They can be properly reviewed. Making mistakes is easy with shell scripts, and they can be very damaging. Code review should be mandatory for shell scripts, as for any other piece of code.
They can be improved. I won't explain to you what version control is. But with shell scripts versioned, it's easy to improve them regularly.

Please, from now on, version all your shell scripts before running them. Have someone reviewing your scripts in priority before executing them in production. It's not a waste of your coworkers' time, it's a time saver for the team.

Improve the quality of your scripts with ShellCheck

Although you can check the syntactic validity of your scripts with the command bash -n, much powerful tools exist.

ShellCheck is a static code analysis tool for shell scripts. It's really an awesome tool which will help you improve your skills as you use it. So do use it. You can install it globally on your machine, use it in your continuous integration, and it even integrates perfectly with most major editors. There really are no downsides to using ShellCheck and it can save you from yourself.

If Steam had used ShellCheck in 2015, this line would never have made it to production:

rm -rf "$STEAMROOT/"*

This code violates the SC2115 rule from ShellCheck.

Use Bash unofficial strict mode

The unofficial strict mode comes from Aaron Maxwell's article "Use the Unofficial Bash Strict Mode (Unless You Looove Debugging)". He suggests to start every Bash script with the following lines:

#!/bin/bash
set -euo pipefail
IFS=$'\n\t'

set -e will exit the script if any command returns a non-zero status code. To prevent the option from triggering on commands returning a non-zero status code even when no error occurred, there are two solutions:
using the || true pattern:

command_returning_non_zero || true

temporary disabling the option:

set +e
command_returning_non_zero
set -e

set -u will prevent using an undefined variable. In the case of undefined positional parameters ($1, $2, ...), you can give them a default value with the parameter expansion construct:

my_arg=${1:-"default"}

set -o pipefail will force pipelines to fail on the first non-zero status code.
IFS=$'\n\t' makes iterations and splitting less surprising, in the case of loops mostly. The default for this variable is usually IFS=$' \n\t' but the space as a separator often gives confusing results.

Read the original article for more details and solutions for common challenges when using the strict mode!

The unofficial strict mode is more intrusive than what we've seen before and can be hard to deal with, but it's worth it in the long run. Take the time to try it.

Do some cleanup!

When scripts are interrupted, either because of a user's action or because something bad occurred, most shell scripts don't clean up their mess. In the worst case, they might not restart services they had to temporarily disable. It's a shame given how easy it is to perform some cleanup and error catching with the trap command.

Once again, in "How "Exit Traps" Can Make Your Bash Scripts Way More Robust And Reliable", Aaron Maxwell gives some great advice.

Always add the following in your shell scripts:

cleanup() {
    # ...
}
trap cleanup EXIT

The trap command will execute the cleanup function as soon as the script exits. In this function you could remove temporary files, restart services, or whatever is relevant to your script.

Test your scripts with shUnit2

shUnit2 is a unit testing framework for shell scripts. It's inspired by JUnit. It's available in the standard repositories so you can install it with apt-get install shunit2 on an Ubuntu-based distro.

shUnit2 consists of a shell script you can source in your test file. To use it, there are multiple approaches. In order not to clutter the main script, I prefer writing the tests in a separate file. This means I'll have a script.sh file and a test_script.sh file.

Below is an example for a script offering a function to add two numbers.

add.sh must have the following structure:

add() {
    local a=$1
    local b=$2
    echo $(( a + b ))
}

if [[ "${BASH_SOURCE[0]}" = "$0" ]]; then
    # Main code of the script
    add $1 $2
fi

The [[ "${BASH_SOURCE[0]}" = "$0" ]] test is used to execute the main code only when the script is executed directly, not sourced.

test_add.sh will look like this:

. ./add.sh

test_add() {
    actual=$(add 5 8)
    expected=13
    assertEquals "$expected" "$actual"
}

. shunit2

First, the test file sources the main file add.sh (in Bash, . is an alias to source). The functions it declares are then available in the test script.

The actual tests are simple functions with a name starting by test. At the end, the globally installed shunit2 is sourced and performs its magic.

The test file can then be executed:

$ bash test_add.sh
test_add

Ran 1 test.

OK

The details of what shUnit2 can do are explained in its documentation.

There are alternatives to shUnit2, such as Bats or Roundup but I didn't have a chance to use them yet. Their usage should be relatively similar though. The point of this section is that testing shell scripts is doable and should be done, whatever solution you choose in the end.

Log what your script is doing

In the past, I made the mistake of not logging anything. I liked running a script and seeing it work magically without anything ugly showing in the console. I was wrong, because when something doesn't work as expected, it becomes impossible to know what happened. Running a script is not supposed to feel like magic, it must be somewhat verbose and understandable. For that, please log as much as possible in your scripts.

For this purpose, I usually add the following lines in my scripts:

readonly LOG_FILE="/tmp/$(basename "$0").log"
info()    { echo "[INFO]    $*" | tee -a "$LOG_FILE" >&2 ; }
warning() { echo "[WARNING] $*" | tee -a "$LOG_FILE" >&2 ; }
error()   { echo "[ERROR]   $*" | tee -a "$LOG_FILE" >&2 ; }
fatal()   { echo "[FATAL]   $*" | tee -a "$LOG_FILE" >&2 ; exit 1 ; }

This tiny logging framework allows to easily keep track of whatever happens during the script execution. Logging becomes as simple as writing info "Executing this and that...". Then it's easy to grep on the log file to find something specific. Feel free to improve these functions as you need, with the date, the calling function name (with $FUNCNAME), etc.

I don't use the builtin logger because it requires special privileges to write to /var/log and I'm not fond of its usage. Writing to a log file in /tmp is usually good enough. For cron scripts though you should probably investigate logger.

Use the -v or --verbose of the commands you invoke as needed to improve the quality of your logging.

Learn to debug your scripts

The easiest way to debug a shell script, besides logging, is to run it with bash -x. Another way is to use set -x inside the script. This option will make Bash print every command before its execution, replacing the variables with their real values. Used together with the unofficial strict mode, this method is useful to see what's going on in a script with less risk to break the environment.

It's also worth knowing that a few debuggers for Bash exist, for example bashdb. bashdb works in the same way as gdb, and can be used to add breakpoints, switching to step by step execution, showing the value of variables, etc. You can learn how to use bashdb with the video "Using BashDB to Debug Your Shell Scripts ":

Document your scripts

Any shell script should have a --help option. This doesn't seem easy? It is, thanks to the following wizardry:

#/ Usage: add <first number> <second number>
#/ Compute the sum of two numbers
usage() {
    grep '^#/' "$0" | cut -c4-
    exit 0
}
expr "$*" : ".*--help" > /dev/null && usage

The usage function will print every line starting with #/ comments, without this prefix.

The expr command will check if the string resulting of the concatenation of all the parameters contains --help. If so, it will call usage.

This is definitely not the cleanest way to parse parameters, but this quick method ensures you will add a --help flag.

For the sake of good practices, this StackOverflow post explains how to properly parse a script's parameters using the while/case/shift construct.

To generate HTML documentation from your comments, you can also check shocco.sh, which inspired the above trick.

Random advice

The following is a list of random good practices I've learned the hard way. I'll explain the rationale behind every advice as I go.

Use Bash for scripting

Use Bash by default, Sh if you have to. Try to forget about Ksh, Zsh or Fish unless there are really good reasons to use them. This choice not only ensures your script will work virtually everywhere, but also fosters comprehension of a script by the whole team. You don't write production scripts for yourself.

Use Bashisms

If you use Bash, don't half-use it. Use parameter expansion. Use local and readonly variables. Use improved conditional expressions.

Quote your variables

Even if you know quoting is not required, it's a good habit to always quote variables. The only exception is when you specifically want expansion to occur. More on word splitting.

Name your parameters

This goes without saying, but explicitly naming parameters ($1, $2, ...) makes the code self-documenting and helps readability. The parameter expansion of Bash is a great candidate for naming and assigning default values to positional parameters:

my_arg=${1:-default}

Use subshells as a way to control what's in your global scope

An example is worth a thousand words:

var=1
echo $var
(
    echo $var
    var=5
    echo $var
)
echo $var

will print:

My main usage for this is when I need to temporarily modify $IFS (for iterating over simple CSV-like files for example) and reset it to its original value afterwards.

Use a template

This script template summarizes every snippets shared along this article. I believe it's a good basis for any kind of script.

#!/usr/bin/env bash
set -euo pipefail
IFS=$'\n\t'

#/ Usage:
#/ Description:
#/ Examples:
#/ Options:
#/   --help: Display this help message
usage() { grep '^#/' "$0" | cut -c4- ; exit 0 ; }
expr "$*" : ".*--help" > /dev/null && usage

readonly LOG_FILE="/tmp/$(basename "$0").log"
info()    { echo "[INFO]    $*" | tee -a "$LOG_FILE" >&2 ; }
warning() { echo "[WARNING] $*" | tee -a "$LOG_FILE" >&2 ; }
error()   { echo "[ERROR]   $*" | tee -a "$LOG_FILE" >&2 ; }
fatal()   { echo "[FATAL]   $*" | tee -a "$LOG_FILE" >&2 ; exit 1 ; }

cleanup() {
    # Remove temporary files
    # Restart services
    # ...
}

if [[ "${BASH_SOURCE[0]}" = "$0" ]]; then
    trap cleanup EXIT
    # Script goes here
    # ...
fi

Stay informed

Shell scripting isn't moving that much these days. It's a great reason to read stuff about the topic, it makes it easy to keep up! Here are some interesting resources:

man bash, I bet almost none of you have read it, yet it's a great source of information! And it's not that hard to read, I promise.
@UnixTooltip on Twitter, continuously gives tips and tricks.
Most upvoted Bash questions on StackOverflow
Bash participative documentation on StackOverflow has some interesting examples.
ShellCheck's wiki is a good resource to learn what not to do, and why.
Hacker News and /r/programming, once in a while articles on this subject pop out.

I hope this article brought light on what was possible with shell scripting. The tools are there. You know the practices. Now it's up to you to make scripting a delight to work with, for you and your team!