Clean Code Principles
A collection of principles and patterns for writing clean, readable, and maintainable code.
When to Use This Skill
- Writing new functions or methods
- Refactoring nested or complex code
- Reviewing code for readability
- Discussing code quality improvements
Note: The principles and rules in each document apply to all programming languages. Examples are shown in a specific language for concreteness, but the patterns themselves are language-agnostic.
Important: When refactoring, remove comments that are no longer relevant to the changed code. However, comments that are still valid and provide useful context (e.g., why a decision was made, business rules, workarounds, warnings) must be preserved.
Principles Overview
| Principle | Description | Reference |
|---|---|---|
| Guard Clause Pattern | Fail fast with early returns, keep code flat | guard-clause-pattern.md |
| Function Decomposition | Break large functions into small, focused units | function-decomposition.md |
| Magic Numbers & Strings | Replace unexplained literals with named constants or enums | magic-numbers-and-strings.md |
| DRY Principle | Eliminate duplicated logic with shared abstractions | dry-principle.md |
| Conditional Simplification | Reduce complex branching into clear, readable conditions | conditional-simplification.md |
| Boolean & Flag Parameters | Replace boolean params with enums, methods, or option objects | boolean-and-flag-parameters.md |
Core Philosophy
- Readability First — Code is read far more often than it is written
- Fail Fast — Handle errors and edge cases early, keep the happy path clear
- Single Responsibility — Each function/class should do one thing well
- Minimal Nesting — Flat code is easier to follow than deeply nested code
- Meaningful Names — Names should reveal intent without needing comments
- DRY, but not at the cost of clarity — Avoid premature abstraction