# Clean Code

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

---

## 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

- **Do one thing** — if you can extract a meaningful function from it, it's doing two things
- **One level of abstraction per function** — don't mix high-level orchestration with low-level detail in the same function
- Keep short — aim for under 20 lines; use extract method aggressively
- 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

## Classes

- **Single Responsibility Principle** — one reason to change
- Small and cohesive — methods should use the class's fields, not act as utilities
- Hide internals: public API simple, private implementation complex
- No god classes — prefer `InvoiceCalculator` over `BusinessLogic`

## Error Handling

- Throw exceptions, don't return error codes — let callers handle what they understand
- Descriptive messages: `throw new UnauthorizedAccess("Admin role required for this action")`
- Define custom exceptions close to where they're used
- Clean up resources: use try/finally or RAII patterns; never leak

## Comments

- Good code needs no comments — if you need to explain *what*, rename instead
- Comments explain *why*, not *what*: acceptable for non-obvious decisions, legal notices
- TODOs are temporary; remove before merging
- Never commit commented-out code

## Formatting

- Related code stays close — declarations near first use
- Consistent indentation throughout the codebase — agree once, automate with linting
- No deep nesting — if you're 4 levels deep, extract a function
- Team standard beats personal preference every time

## General Principles

- **DRY** — every piece of knowledge has one representation; duplication is a maintenance liability
- **KISS** — the simplest solution that works; complexity must earn its place
- **Boy Scout Rule** — leave the code cleaner than you found it; small improvements compound
- **SOLID** — especially SRP (above) and Open-Closed: open for extension, closed for modification
- **Boundaries** — wrap third-party code in adapters; don't let external APIs bleed through the codebase

## Testing

- Tests must be **FAST, Independent, Repeatable, Self-Validating**
- One concept per test — a test that asserts many things is a test that hides failures
- Keep test code as clean as production code — it will be maintained just as long
- Write code testable from day one; retrofitting testability is expensive

---

## In Helm Charts and YAML

The same principles apply to configuration:

- **Naming**: value keys should be intention-revealing — `replicaCount` not `rc`, `service.port` not `p`
- **Single responsibility**: one chart does one thing; don't bundle unrelated services
- **No magic values**: named values in `values.yaml`, never hardcoded in templates
- **DRY**: use template helpers (`_helpers.tpl`) to avoid repeating label blocks and name patterns
- **Comments**: explain *why* a value is set a certain way, not what it does — the YAML speaks for itself
- **Defaults that make sense**: a default of `false` or `""` that always needs overriding is not a useful default