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

clean-code-principles

Clean Code Principles

When to Use This Skill

Principles Overview

Core Philosophy