Clean Code

Professional code craftsmanship based on Robert C. Martin's principles.

When to Use

• •Writing/refactoring code
• •Code review and quality assessment
• •Establishing coding standards
• •Detecting and fixing code smells

Quick References

• •Quick start: references/quick-start.md
• •Theory: CORE_PRACTICES.md
• •Language-specific: references/naming-conventions.md
• •Code smells: references/code-smells.md

Core Principles

1. Meaningful Names

Names reveal intent and enable understanding without reading implementation.

Rules:

• •Pronounceable, searchable, revealing intent
• •Avoid l (lowercase L) or O (uppercase o)
• •Classes: nouns (Customer, Account)
• •Methods: verbs (postPayment(), save())
• •One word per concept
• •Professional terminology

Bad: def d(): return (currentTime() - lastModifiedTime()) / 86400 Good: def get_days_since_last_modification(): ...

2. Functions

Functions should be small, focused, and single-purpose.

Rules:

• •Small (ideally <20 lines)
• •Do one thing well (SRP)
• •Minimal parameters (0-2 ideal, max 3)
• •No side effects beyond stated purpose
• •Use exceptions, not error codes
• •Extract duplication (DRY)
• •No flag parameters

Bad: process_user_data(data, flag1, flag2, flag3) - 100 lines, multiple purposes Good: Decompose into focused functions with clear names

3. Comments

Self-documenting code is best. Comments explain WHY, not WHAT.

Write comments for: Business logic, non-obvious decisions, warnings, legal info Don't write for: Obvious code, redundant text, commented-out code

4. Formatting

Code formatting improves readability. Choose conventions and follow consistently.

Key rules:

• •Consistent indentation (2-4 spaces)
• •Lines under 80-120 characters
• •Blank lines separate logical groups
• •Consistent bracket placement
• •Group related code together

5. Error Handling

Handle errors explicitly and clearly. Use exceptions over error codes.

Key rules:

• •Use exceptions, not error codes
• •Provide context with exceptions
• •Custom exception types for different scenarios
• •Use try-finally or context managers for cleanup
• •Don't silently catch and ignore errors
• •Avoid returning null (use exceptions or special objects)

6. Code Smells Detection

Recognize patterns that indicate deeper problems requiring refactoring.

See references/code-smells.md for comprehensive list of code smells and refactoring techniques.

Common Smells:

• •Duplicate Code - Extract to shared function
• •Long Methods - Break into smaller focused functions
• •Long Parameter Lists - Use object parameters or refactor
• •Divergent Change - One class changed for multiple reasons (violates single responsibility)
• •Shotgun Surgery - One change requires edits across many classes
• •Feature Envy - Method uses more of another class than its own
• •Data Clumps - Groups of variables passed together (extract to objects)
• •Magic Numbers - Use named constants

Workflow: Code Review & Refactoring

Review: Check names, functions, comments, formatting, error handling, code smells Refactor: Identify issues → write tests → make changes → run tests → document

Key Takeaways

1. •Code is read far more than written - optimize for readability
2. •Names reveal intent - spend time on meaningful names
3. •Functions stay small and focused - one responsibility each
4. •Comments explain WHY, not WHAT
5. •Exceptions over error codes or null returns
6. •Refactoring is ongoing - clean code requires continuous improvement

Source: Clean Code: A Handbook of Agile Software Craftsmanship by Robert C. Martin