principle-clean-codelisted

<!-- preload-canary: SWB-PRELOAD-PRINCIPLE-CLEAN-CODE --> # 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 | ~10 lines | | KDoc | Kotlin | ~10 lines | | docstring | Python | ~8 lines | | rustdoc | Rust | ~8 lines | | TSDoc/JSDoc | TypeScript, JavaScript | ~8 lines | | Swift markup | Swift | ~8 lines | | XML doc | C# | ~8 lines | | YARD/RDoc | Ruby | ~6 lines | | dartdoc | Dart | ~6 lines | Caps are soft — a well-justi