shell-conventions

name	shell-conventions
description	Functional shell conventions for POSIX sh, bash, and zsh. Use when writing or editing shell scripts (.sh/.bash) or zsh config (.zsh, prompts, hooks, completions, aliases).

Shell Conventions

One root — predictability: the same construct chosen every time, so a script's behavior is legible from its text and a class of bugs never occurs.

Functional core, imperative shell is how we get there: logic expressed as pure functions, immutable values, and composition; side effects quarantined at the edges. Adhere to it wherever the dialect allows.

A file commits to one dialect, declared by its shebang — never mix them. Before writing, read the dialect's file; it holds the concrete syntax that realizes the tenets below:

• posix.md — portable scripts (#!/usr/bin/env sh)
• bash.md — bash scripts
• zsh.md — zsh scripts and interactive config (prompts, hooks, completions)

When a choice between forms is otherwise arbitrary, pick the one written here.

The functional paradigm (all shells)

Pure functions

A function is pure when it reads only its arguments and writes only its return channel — no global read or written, no file touched, no environment mutated. Same inputs, same output, every time.

• Return scalars on stdout; return collections by the dialect's indirection. Reserve the exit status for success/failure, not data.
• Pass every input explicitly. A function that reads $VERBOSE from the environment is reading a global — make it an argument.
• A function that cds, exports, writes a file, or calls exit is impure; push that work to the edges.

Immutability

• Declare a value once, never reassign: readonly at top level, local -r in functions.
• Treat collections as values — a transform reads its input read-only and emits a fresh result rather than mutating in place.

First-class & higher-order functions

A function name is a first-class value: pass it as a string, invoke it through the variable ("$fn" "$@"). Functions that take or return functions — map, filter, reduce, compose — are the vocabulary. Reach for them before writing a bespoke loop; each dialect file gives the concrete implementation.

Composition

Build large transforms from small pure ones:

• Pipelines — the shell's native left-to-right composition, one process per stage. Prefer them when each stage streams.
• Nested calls — right-to-left composition for scalars: f "$(g "$(h "$x")")".
• A named helper when a composition recurs (portable — command substitution and positional parameters only):

chain() {          # chain val f g h  ==  h(g(f(val)))
	local acc=$1; shift
	for fn in "$@"; do
		acc=$("$fn" "$acc")
	done
	printf '%s' "$acc"
}

Wrap a pipeline in a function to name the composition; it is itself pure if every stage is.

Recursion

For naturally recursive problems (tree walks, fold-style accumulation), recursion reads clearer than a state-mutating loop. Each call costs a stack frame and each $(...) a subshell fork, so loops still win for very deep iteration — recurse for clarity, not by default.

Effects at the edges

Side effects are unavoidable at the boundaries: I/O, processes, environment. Concentrate them.

• main and a thin layer of I/O wrappers carry every read, write, cd, exec, export, and trap. The pure core never sees them.
• Contain an unavoidable cd in a subshell: ( cd -- "$dir" && cmd ) does not change the caller's working directory.
• A function passed a tempfile path stays pure; one that creates the tempfile does not.

Common rules (all shells)

• Safety over brevity. Strict mode on every script, quoting on every expansion, local on every variable. Verbosity that prevents a class of bugs is cheaper than the bug. (Strict-mode syntax is in each dialect file.)
• Quote every expansion: "$var", "$(cmd)", and "${array[@]}" where arrays exist. Single-quote literals containing $, backticks, or backslashes to opt out of expansion entirely.
• -- before variable arguments to commands that accept flags: rm -- "$file", cd -- "$dir".
• printf '%s\n' "$x" over echo "$x". echo interprets -e/-n/backslashes inconsistently across shells and versions.
• Errors to stderr: printf '%s\n' "msg" >&2.
• Never eval — it breaks referential transparency and invites injection. Use the dialect's indirection instead.
• Naming. snake_case for functions and variables; UPPER_SNAKE_CASE for exported variables and readonly constants. Function names are verbs (build_index, parse_args); predicates start with is_/has_ and return via exit status; array variables are plural (files, users). One-letter names only inside tight numeric loops (i, j).
• Formatting. Indent with tabs. Multi-line bodies for every if, for, while; never write the body on the header line. One blank line between top-level functions. Break long pipelines and commands with \ continuations, the continuation indented one tab past the header.

Done means

Sweep every line you wrote or touched: strict mode present, every expansion quoted, every function variable local, -- before variable arguments, effects only at the edges, the dialect file's rules applied. Every touched line — not most.