---
paths:
  - "**/*.sh"
  - "bashrc"
  - "bin/*"
---

# 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

```bash
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[@]}"`
- 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