Bash Style Guide and Best Practices

1. Why Style Matters and How to Automate It

In a professional DevOps environment, you rarely write code that only you will see. Your scripts become part of a larger system, maintained by a team. Writing with a consistent style offers several key benefits:

• Readability: Code is read far more often than it is written. A clear, consistent style makes it easier for others (and your future self) to understand what a script does.
• Maintainability: When you need to fix a bug or add a feature, well-structured code is faster and safer to modify.
• Collaboration: When everyone on a team follows the same conventions, it reduces friction and makes code reviews more efficient.
• Bug Reduction: Many style guide rules are designed to prevent common, subtle bugs related to things like word splitting and error handling.

The best way to start applying these rules is to use a tool that automates the process. The most popular tool for this is ShellCheck.

Introducing ShellCheck: Your Automated Code Reviewer

ShellCheck is a static analysis tool that scans your shell scripts and provides warnings and suggestions for common issues. It's like a spell-checker for your code, catching everything from simple syntax errors to complex logical flaws.

Many code editors (like VS Code) have extensions that integrate ShellCheck, providing real-time feedback as you type. Adopting ShellCheck early is one of the single best habits you can form.

Let's read about ShellCheck in one of the most respected style guides available.

2. Core Principles of a Bash Style Guide

While ShellCheck is fantastic, it's also important to understand the principles behind its suggestions. We'll now explore the key pillars of a good style guide, using Google's guide as our foundation.

A. Readability and Structure

This set of rules is designed to make scripts easy to read and navigate.

• Comments: Good comments explain the why, not the how. A file should start with a header explaining its purpose, and any non-obvious function should have a comment block explaining what it does, its arguments, and what it returns.
• Naming Conventions: Use a consistent naming scheme. A common convention is lower_case_with_underscores for functions and variables, and ALL_CAPS for constants and environment variables.
• Formatting: Consistent indentation (2 spaces is common, no tabs), a reasonable line length (80 characters is the classic standard), and clear formatting for long commands or pipelines make code visually clean.

B. Writing Robust and Safe Code

This is arguably the most critical part of any style guide, as these rules directly help prevent bugs.

• Quoting: This is a big one. Always double-quote your variables ("$var") and command substitutions ("$(command)"). This prevents the shell from performing word splitting and glob expansion on values that contain spaces or special characters (*, ?), which is a massive source of bugs.
• Conditionals: Prefer using the double-bracket [[ ... ]] test construct over the single-bracket [ ... ]. [[ is a Bash keyword with more features and safer behavior; for example, it doesn't perform word splitting on variables, which simplifies tests.
• Error Handling: A command can fail. Don't assume cd will always succeed. Always check for failures on critical commands, for example: cd /some/dir || exit 1.
• Dangerous Commands: Some commands are best avoided entirely. eval is extremely dangerous as it can execute arbitrary code passed in its arguments. Similarly, parsing the output of ls is unreliable; use globbing (for f in *; do ...) instead.

C. Consistency is King

You may have noticed that the Google guide and the bahamas10 guide have some different opinions (e.g., spaces vs. tabs, using the function keyword). This is normal. There is no single, universally-enforced style guide for Bash.

The most important rule of all is to be consistent. If you are working on an existing project, follow its style. If you are starting a new project, choose a guide and stick to it. This principle outweighs any minor debate over specific rules.

#!/bin/bash
# script to process logs

FILES=/var/log/*.log
for f in $FILES
do
  if [ -f $f ]; then
    echo "Processing " $f
    cat $f | grep 'ERROR' > /tmp/errors.txt
  fi
done

CONST=100
echo "Done. Constant is" $CONST

#!/usr/bin/env bash
#
# Processes all .log files in /var/log for lines containing 'ERROR' and
# saves them to a temporary file.

# A constant should be all caps and readonly.
readonly TMP_FILE="/tmp/errors.txt"

# Clear the temp file before starting.
> "${TMP_FILE}"

# Use a glob directly in the loop.
# Quote all variables to prevent word-splitting issues.
for f in /var/log/*.log; do
  # Use the safer and more powerful [[ ... ]] for tests.
  if [[ -f "${f}" ]]; then
    echo "Processing ${f}..."
    # Avoid 'Useless Use of Cat'. grep can read files directly.
    # Append to the file instead of overwriting it in each loop iteration.
    grep 'ERROR' "${f}" >> "${TMP_FILE}"
  fi
done

echo "Done. Errors saved to ${TMP_FILE}"

Conclusion

You have now completed the core lessons for Bash scripting! You've gone from basic commands to writing functions, processing structured data, and finally, understanding the principles of professional software development as they apply to shell scripts.

Key Takeaways:

• Style guides matter: They improve readability, maintainability, and collaboration while reducing bugs.
• Use a linter: ShellCheck is an essential tool for automatically finding and fixing common problems in your scripts.
• Write safe code: Always quote variables ("$var"), use [[...]] for tests, and check for errors on critical commands.
• Write clean code: Use consistent naming conventions, formatting, and add comments to explain the why.
• Be consistent: The most important rule is to pick a style for your project and stick to it.

Next Up

In the next module, "Practical Bash Automation Projects," you will put all this knowledge to use. Your first task will be to write a Bash script to capture and display current CPU, memory, and disk usage. This is a classic DevOps task, and with your new understanding of functions, command substitution, and style, you're perfectly prepared to build a professional-quality tool.