principle-clean-codelisted

# Clean Code ## Function Rules | Rule | Guideline | |------|-----------| | **Function length** | Prefer under 20 lines. Extract when doing two things. | | **Naming** | Name reveals intent. No abbreviations except universal ones (ctx, err, id). | | **Abstraction level** | One level per function. Don't mix SQL strings with business logic. | | **Comments** | Explain WHY, not WHAT. If code needs WHAT comments, rename or extract. See Comment discipline. | | **Error handling** | Handle at the appropriate layer. Don't swallow errors silently. | | **Argument count** | 0 is ideal; 1 is common; 2 is acceptable; 3+ is suspicious. A boolean flag argument is a hidden second function — split it. | | **Command-Query Separation** | A function either changes state or returns a value — not both. | ## Comment discipline *A comment is a cost paid on every future read — spend the budget on WHY, not WHAT.* Doc-comment styles, named so authoring and review flows share one term set: | Style | Language | Soft cap | |-------|----------|----------| | Inline (`//`, `#`) | any | ≤2 lines | | godoc | Go | ~4 lines | | javadoc | Java, Kotlin | ~10 lines | | docstring | Python | ~8 lines | | rustdoc | Rust | ~8 lines | Caps are soft — a well-justified doc comment can exceed them, but a comment that runs long without adding information past the cap is a signal to trim. An **unnecessary comment** is any of: - **WHAT-not-WHY** — describes what the code does instead of why it does it; well-named code alr