Bash Readability Style

The primary goal is code that is easy to understand at a glance. Write bash that reads naturally, follows established conventions, and doesn't require the reader to puzzle over clever tricks. Favor clarity and well-known idioms over brevity.

Complements CLAUDE.md. Does not repeat rules already defined there.

Formatting

2-space indentation, no tabs
then/do on same line: if cond; then / for x in list; do
Blank lines between logical sections; no blanks between tightly coupled statements
Long pipe chains: one command per line with leading |

Naming

UPPER_CASE — exported env vars and constants; use readonly for true constants
snake_case — local variables and function names
verb_noun pattern for functions: set_ps1_prompt, docker_aws_login
Meaningful names, no single letters except loop counters (i, f)

Functions

function do_thing() {
  local name="$1"
  local count="${2:-0}"
  ...
}

Always function name() { declaration style
Always local for function variables, assigned on declaration line
Name parameters immediately: local filename="$1" — no raw $1 in logic
Default values via ${VAR:-default}
Guard clauses with early return over deep nesting
Keep functions focused — single responsibility

Syntax Preferences

[[ ]] over [ ] for conditionals
(( )) for arithmetic comparisons
$(command) for substitution, never backticks
Double quotes around expansions: "$var", "${array[@]}"
Quote the whole string, not just the variable: "$HOME/.local/bin" not "$HOME"/.local/bin
Single quotes for literals that must not expand
printf over echo when output contains escapes or format strings

Resource Cleanup

Consider trap cleanup EXIT with mktemp when scripts create temporary files/dirs or acquire resources; skip when it would add unnecessary complexity (short scripts, no temp state)

Structured Data

Prefer jq for JSON and yq for YAML over ad-hoc grep/awk/string splitting
Treat parser errors as fatal; check exit status before using results

Commands

Long options for clarity: --recursive not -r (common test flags -f, -d, -e are fine)
Redirect stderr: > /dev/null 2>&1
# shellcheck shell=bash at top of sourced (non-executable) files

Comments

Minimal — explain why, not what
URL reference when pattern comes from external source
No banner/divider comments

2.5 KiB Raw Blame History