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.

3.1 KiB Raw Blame History Unescape Escape