Robert C. Martin (Uncle Bob) Clean Code Best Practices

Comprehensive software craftsmanship guide based on Robert C. Martin's "Clean Code: A Handbook of Agile Software Craftsmanship". Contains 45 rules across 8 categories, prioritized by impact to guide code reviews, refactoring decisions, and new development.

When to Apply

Reference these guidelines when:

• Writing new functions, classes, or modules

• Naming variables, functions, classes, or files

• Reviewing code for maintainability issues

• Refactoring existing code to improve clarity

• Writing or improving unit tests

Rule Categories by Priority

Priority Category Impact Prefix

1 Meaningful Names CRITICAL name-

2 Functions CRITICAL func-

3 Comments HIGH cmt-

4 Formatting HIGH fmt-

5 Objects and Data Structures MEDIUM-HIGH obj-

6 Error Handling MEDIUM-HIGH err-

7 Unit Tests MEDIUM test-

8 Classes and Systems MEDIUM class-

Quick Reference

1. Meaningful Names (CRITICAL)

• name-intention-revealing

• Use names that reveal intent

• name-avoid-disinformation

• Avoid misleading names

• name-meaningful-distinctions

• Make meaningful distinctions

• name-pronounceable

• Use pronounceable names

• name-searchable

• Use searchable names

• name-avoid-encodings

• Avoid encodings in names

• name-class-noun

• Use noun phrases for class names

• name-method-verb

• Use verb phrases for method names

2. Functions (CRITICAL)

• func-small

• Keep functions small

• func-one-thing

• Functions should do one thing

• func-abstraction-level

• Maintain one level of abstraction

• func-minimize-arguments

• Minimize function arguments

• func-no-side-effects

• Avoid side effects

• func-command-query-separation

• Separate commands from queries

• func-prefer-exceptions

• Prefer exceptions to error codes

• func-dry

• Do not repeat yourself

3. Comments (HIGH)

• cmt-express-in-code

• Express yourself in code, not comments

• cmt-explain-intent

• Use comments to explain intent

• cmt-avoid-redundant

• Avoid redundant comments

• cmt-avoid-commented-out-code

• Delete commented-out code

• cmt-warning-consequences

• Use warning comments for consequences

4. Formatting (HIGH)

• fmt-vertical-formatting

• Use vertical formatting for readability

• fmt-horizontal-alignment

• Avoid horizontal alignment

• fmt-team-rules

• Follow team formatting rules

• fmt-indentation

• Respect indentation rules

5. Objects and Data Structures (MEDIUM-HIGH)

• obj-data-abstraction

• Hide data behind abstractions

• obj-data-object-asymmetry

• Understand data/object anti-symmetry

• obj-law-of-demeter

• Follow the Law of Demeter

• obj-avoid-hybrids

• Avoid hybrid data-object structures

• obj-dto

• Use DTOs for data transfer

6. Error Handling (MEDIUM-HIGH)

• err-use-exceptions

• Use exceptions instead of return codes

• err-write-try-catch-first

• Write try-catch-finally first

• err-provide-context

• Provide context with exceptions

• err-define-by-caller-needs

• Define exceptions by caller needs

• err-avoid-null

• Avoid returning and passing null

7. Unit Tests (MEDIUM)

• test-first-law

• Follow the three laws of TDD

• test-keep-clean

• Keep tests clean

• test-one-assert

• One assert per test

• test-first-principles

• Follow FIRST principles

• test-build-operate-check

• Use Build-Operate-Check pattern

8. Classes and Systems (MEDIUM)

• class-small

• Keep classes small

• class-cohesion

• Maintain class cohesion

• class-organize-for-change

• Organize classes for change

• class-isolate-from-change

• Isolate classes from change

• class-separate-concerns

• Separate construction from use

How to Use

Read individual reference files for detailed explanations and code examples:

• Section definitions - Category structure and impact levels

• Rule template - Template for adding new rules

Reference Files

File Description

references/_sections.md Category definitions and ordering

assets/templates/_template.md Template for new rules

metadata.json Version and reference information