Clean Code

## Rule Title Here

Brief explanation of the rule and why it matters. Focus on the principle and its impact on code maintainability and readability.

**Incorrect (description of what's wrong):**

```java
// Bad code example here showing the anti-pattern
// Comment explaining the problem
```

**Correct (description of what's right):**

```java
// Good code example here showing the solution
// Comment explaining the benefit
```

**When NOT to use this pattern:**
- Exception case 1
- Exception case 2

Reference: [Clean Code, Chapter N: Topic](https://www.oreilly.com/library/view/clean-code-a/9780136083238/)


{
  "version": "1.0.7",
  "organization": "Robert C. Martin (Uncle Bob)",
  "technology": "Software Craftsmanship (examples in Java, principles are language-agnostic)",
  "date": "January 2026",
  "abstract": "Comprehensive software craftsmanship guide based on Robert C. Martin's 'Clean Code: A Handbook of Agile Software Craftsmanship', updated with modern corrections where the original 2008 advice has been superseded. Contains 48 rules across 10 categories covering naming, functions, comments, formatting, error handling, objects, boundaries, classes, testing, and simple design. Each rule includes 'When NOT to use' caveats, polyglot guidance where applicable, and real-world examples comparing incorrect vs. correct implementations.",
  "references": [
    "https://www.oreilly.com/library/view/clean-code-a/9780136083238/",
    "https://blog.cleancoder.com/",
    "https://www.amazon.com/Clean-Code-Handbook-Software-Craftsmanship/dp/0132350882"
  ]
}


# Sections

This file defines all sections, their ordering, impact levels, and descriptions.
The section ID (in parentheses) is the filename prefix used to group rules.

---

## 1. Meaningful Names (name)

**Impact:** CRITICAL
**Description:** Names are the primary documentation. Bad names cascade confusion throughout the codebase, forcing every reader to decipher intent.

## 2. Functions (func)

**Impact:** CRITICAL
**Description:** Functions are the verbs of code. Small, focused functions enable understanding, testing, and reuse while reducing complexity.

## 3. Comments (cmt)

**Impact:** HIGH
**Description:** Comments should explain intent, not obvious mechanics. Wrong or stale comments actively mislead readers and cost more than no comments.

## 4. Formatting (fmt)

**Impact:** HIGH
**Description:** Consistent formatting reduces cognitive load. Code should read top-to-bottom like a newspaper article.

## 5. Error Handling (err)

**Impact:** HIGH
**Description:** Clean error handling separates happy path from exceptional cases. Use the error mechanism idiomatic to your language (exceptions, Result types, or explicit error returns).

## 6. Objects and Data Structures (obj)

**Impact:** MEDIUM-HIGH
**Description:** Objects hide data and expose behavior; data structures expose data and have no behavior. Mixing these creates hybrid messes.

## 7. Boundaries (bound)

**Impact:** MEDIUM-HIGH
**Description:** Third-party code and external APIs are boundaries. Wrap them to isolate change, ease testing, and maintain control over your codebase's interfaces.

## 8. Classes and Systems (class)

**Impact:** MEDIUM-HIGH
**Description:** Classes should be small and have a single responsibility. Systems should separate construction from use. SRP and DIP are among the highest-leverage design principles.

## 9. Unit Tests (test)

**Impact:** MEDIUM
**Description:** Tests are first-class citizens that enable safe refactoring. Test code deserves the same care as production code.

## 10. Emergence and Simple Design (emerge)

**Impact:** MEDIUM
**Description:** Good design emerges from following four rules in order: pass tests, reveal intent, eliminate duplication, minimize elements. Resist the urge to over-engineer.


---
title: Write Lear