Prelude

The goal of this guide is to present a set of best practices and coding style idioms for bash shell scripting. The style guide is inspired by Eloquent Ruby, the The Ruby Style Guide and the elegant syntax of the ruby programming language.

Nobody really knows what the Bourne shell's grammar is.
Even examination of the source code is little help.
-- Tom Duff

The AJAlabs Bash Scripting Style Guide

The AJAlabs bash scripting style guide recommends best practices so that real-world IT professionals and bash programmers can write code that can be maintained by other real-world professionals and programmers. A style guide that reflects real-world usage gets used, and a style guide that holds to an ideal that has been rejected by the people it is supposed to help risks not getting used at all – no matter how good it is.

The guide is separated into several sections of related rules. I've tried to add the rationale behind the rules (if it's omitted I've assumed it's pretty obvious).

Table of Contents

• Source Code Layout
• Syntax
• Naming
• Comments
• Resources

Source Code Layout

Nearly everybody is convinced that every style but their own is ugly and unreadable. Leave out the "but their own" and they're probably right...
-- Jerry Coffin (on indentation)

• Use UTF-8 as the source file encoding. ^[link]

• Always use a portable shebang on the first line of your script. ^[link]

  # bad - absolute path
  #!/bin/bash
  
  # good
  #!/usr/bin/env bash
  

• Use two spaces per indentation level (aka soft tabs). No hard tabs. ^[link]

  # bad - four spaces
  if [ "foo" = "foo" ]; then
      do_something
  else
      do_something_else
  fi
  
  # good
  if [ "foo" = "foo" ]; then
    do_something
  else
    do_something_else
  fi

• Use LF Unix-style line endings. (*BSD/Solaris/Linux/OS X users are covered by default, Windows users have to be extra careful.) ^[link]

  • If you're using Git you might want to add the following configuration setting to protect your project from Windows line endings creeping in:

    $ git config --global core.autocrlf true

• Don't use ; to separate statements and expressions. As a corollary - use one expression per line. ^[link]

  # bad
  echo 'foobar'; # superfluous semicolon
  
  echo 'foo'; echo 'bar' # two expressions on the same line
  
  # good
  echo 'foobar'
  
  echo 'foo'
  echo 'bar'

Syntax

Naming

Comments

Good code is its own best documentation. As you're about to add a comment, ask yourself, "How can I improve the code so that this comment isn't needed?" Improve the code and then document it to make it even clearer.
-- Steve McConnell

• Write self-documenting code and ignore the rest of this section. Seriously! ^[link]

• Write comments in English. ^[link]

• Use one space between the leading # character of the comment and the text of the comment. ^[link]

• Comments longer than a word are capitalized and use punctuation. Use one space after periods. ^[link]

• Avoid superfluous comments. ^[link]

  # bad
  counter=$((counter+1)) # Increments counter by one.

• Keep existing comments up-to-date. An outdated comment is worse than no comment at all. ^[link]

Good code is like a good joke - it needs no explanation.
-- Russ Olsen

• Avoid writing comments to explain bad code. Refactor the code to make it self-explanatory. (Do or do not - there is no try. --Yoda) ^[link]

How to Contribute?

It's easy, just follow the contribution guidelines.

License

This work is licensed under a Creative Commons Attribution 3.0 Unported License

Spread the Word

The hope is that this guide becomes a community-driven style guide. A community-driven style guide is of little use to a community that doesn't know about its existence. Tweet about the guide, share it with your friends and colleagues. Every comment, suggestion or opinion we get makes the guide just a little bit better. And we want to have the best possible guide, don't we?

Resources

• Bash Guide for Beginners: HTML PDF
• Advanced Bash-Scripting Guide: HTML PDF
• Bash Reference Manual: HTML PDF
• bash Cookbook
• Classic Shell Scripting
• bash Pocket Reference