# Clean Code Reference Guide

Based on Robert C. Martin's *Clean Code*. Apply these principles to all code and configuration, including Helm charts, YAML, and infrastructure-as-code.

## Full Clean Code Guidelines

### Naming
- Use intention-revealing names: `daysSinceLastPayment` not `d`
- Don't lie with names: `accounts` not `accountList` if it isn't a list
- Pronounceable, searchable names — avoid encodings like `a2dp`, `strName`
- One word per concept across the codebase: pick `fetch`, `get`, or `retrieve` — not all three
- Names should read like prose: `if user.isEligibleForRefund()` not `if user.check()`

### Functions
- **0–2 arguments preferred**; use a parameter object when more are needed
- **No side effects** — a function named `checkPassword` must not also start a session
- No flag arguments: `delete(file, true)` means the function already does two things — split it

### Newspaper Readability
Code should read like a good newspaper article: the headline (function/class name) tells you everything, the opening paragraph gives the high-level story, and the details follow below in order.

- **High-level first** — the top-level function appears at the top of the file; it calls lower-level helpers that follow below it in the order they are called
- **One thought per "paragraph"** — one function = one clear theme
- **Consistent vocabulary** — use the same terms throughout
- **Smooth flow** — control flow reads top-to-bottom

### Declarative and Imperative Layers
Well-structured code has a clear layer boundary between *what* and *how*.
- **Top layer — declarative**: reads like a description of intent. No loops, no conditionals on mechanics.
- **Middle layer — declarative**: coordinates steps and error paths.
- **Bottom layer — imperative**: the actual mechanics (SQL, string parsing, arithmetic). This is the only layer where implementation details belong.

### Comments
**The default is no comments.** A comment is only justified when the code cannot speak for itself — meaning the *why* is non-obvious:
- **Allowed:** Explaining a bug/quirk in a dependency, non-obvious platform behaviour, or timing constraints.
- **Forbidden:** Describing what the function does, section dividers (`# --- Config ---`), left-over TODOs, or commented-out code.

### Formatting & Optical Illusions
- Always use braces for `if`, `for`, `while` — even for single-line bodies.
- **Avoid optical illusions** — code that looks like it does one thing but does another. Examples:
  - Side effects hidden in expressions: `list.sort()` returning void
  - Formatting that suggests grouping without braces

### General Principles
- **DRY** — Don't Repeat Yourself.
- **KISS** — Keep It Simple, Stupid.
- **Boy Scout Rule** — leave the code cleaner than you found it.
- **SOLID** — Single Responsibility, Open-Closed, Liskov Substitution, Interface Segregation, Dependency Inversion.

### In Helm Charts and YAML
The same principles apply to configuration:
- **Naming**: intention-revealing keys (`replicaCount` not `rc`).
- **DRY**: use template helpers (`_helpers.tpl`) to avoid repeating label blocks.
- **Comments**: only when a value's *why* is non-obvious.