74 lines
2.4 KiB
Markdown
74 lines
2.4 KiB
Markdown
---
|
|
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
|