Essential Shell Script Coding Standards for Clean, Efficient Automation

Introduction

Due to work requirements the author revisited shell scripting, noting that while most commands are familiar, scripts often look messy and hard to read. Shell scripts are more a tool than a formal programming language, leading to inconsistent styles and difficulty in standardizing code.

Code Style Guidelines

Shebang

The shebang ("#!") on the first line specifies the interpreter when none is given. Use a portable shebang like #!/usr/bin/env bash rather than hard‑coding a path.

Comments

Comments are essential in shell scripts to explain purpose, parameters, usage, warnings, author information, and function details. Treat comments like a README for each script.

Parameter Validation

Validate the number and format of parameters early and provide clear usage messages.

Variables and Magic Numbers

Define important environment variables at the top of the script and avoid hard‑coded magic numbers; use named variables instead.

Indentation

Consistently indent blocks (e.g., if, for) using either soft tabs (2 or 4 spaces) or hard tabs, but avoid mixing styles.

Naming Conventions

File names should end with .sh.

Variable names must be meaningful and spelled correctly.

Use lowercase with underscores for variable names.

Encoding

Prefer UTF‑8 encoding without BOM, especially when editing on Windows. Use English for comments and log messages to avoid garbled output.

Permissions

Remember to set executable permissions ( chmod +x script.sh) so the script can run directly.

Logging and Echo

Provide real‑time feedback during execution, optionally using ANSI color codes for better user experience.

Password Handling

Never hard‑code passwords in scripts; keep credentials out of version control.

Line Continuation

Break long command lines with a backslash ( \) followed by a space for readability.

Structuring with a Main Function

Encapsulate the primary logic in a main() function and call it at the end, improving readability similar to compiled languages.

Scope Management

By default variables are global; use local or readonly inside functions to limit scope and avoid side effects.

Function Return Values

Shell functions return integer status codes (0 for success). To return strings, echo the value and capture it.

Indirect Variable Reference

Use the ! syntax for simple indirect references (e.g., echo ${!VAR2}). For assignment, eval may be required, though it is discouraged.

Heredocs

Use heredocs ( <<EOF) to embed multi‑line content such as template files.

Path Resolution

Prefer absolute paths or $(dirname "$0") to reliably locate the script’s directory, rather than relying on pwd.

Keep Code Concise

Prefer single commands that accomplish the task instead of chaining multiple commands; concise code improves readability and performance.

Parallel Execution

Use & and wait for simple parallelism, or xargs -P for controlled concurrency.

Modern Syntax

Define functions with func() {} instead of func{}.

Prefer [[ ]] over [ ].

Use $() instead of backticks for command substitution.

Prefer printf over echo for complex output.

Additional Tips

Use absolute paths; if relative, prefix with ./.

Prefer Bash parameter expansion over awk / sed for simple tasks.

Write simple conditionals as one‑liners with && and ||.

Namespace exported variables to avoid collisions.

Use trap to handle termination signals.

Create temporary files with mktemp.

Redirect unwanted output to /dev/null.

Check command exit statuses to detect failures.

Test file existence before operating on them.

Avoid parsing ls output.

Read files with while read loops instead of for loops.

Static Analysis with ShellCheck

Overview

ShellCheck is an open‑source static analysis tool for shell scripts, widely adopted with over 8 000 GitHub stars.

Installation

Available on major platforms (Debian, Arch, Gentoo, EPEL, Fedora, macOS, openSUSE, etc.) via standard package managers.

Integration

Can be integrated into CI pipelines such as Travis CI to automatically lint shell scripts.

Examples

The tool’s documentation includes a “Gallery of bad code” that serves as a reference similar to “Java Puzzlers”.

Core Value

ShellCheck’s extensive wiki explains each warning, the underlying issue, and recommended fixes, making it invaluable for deep learning.