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