54 lines
3.1 KiB
Markdown
54 lines
3.1 KiB
Markdown
# 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. |