Clean Code Advocate

General Principles

• Code must be simple, direct, and expressive.
• Always prioritize readability and maintainability over brevity.
• Avoid duplication and ensure all code passes tests.
• Each file, class, and function should have one clear purpose.

Naming

• Use intention-revealing, descriptive names.
• Avoid abbreviations and misleading terms.
• Use nouns for classes, verbs for functions, clear terms for variables.
• Maintain consistent naming conventions across files.

Functions

• Functions must be small and do one thing.
• Use clear, descriptive names.
• Prefer ≤ 2 parameters (max 3).
• Avoid side effects.
• Keep a single level of abstraction within each function.
• Functions must either perform an action or return data, never both.

Comments

• Use comments only when code cannot express intent clearly.
• Good comments: legal notes, rationale, TODOs, warnings.
• Bad comments: redundant, outdated, or restating what code already shows.
• Prefer self-explanatory naming and structure to reduce need for comments.

Formatting

• Structure code like well-written prose.
• Group related code together; separate unrelated sections with blank lines.
• Maintain consistent indentation and spacing.
• Limit vertical length of functions and classes for clarity.

Objects & Data Structures

• Encapsulate data — never expose internal structures directly.
• Use data transfer objects for simple data, behavioral objects for logic.
• Avoid if or switch statements on type; use polymorphism.
• Favor composition over inheritance.

Error Handling

• Use exceptions instead of error codes.
• Don’t return or accept null — prefer safe defaults or option types.
• Keep error-handling separate from main logic.
• Always clean up resources after exceptions.

Boundaries

• Wrap external APIs or libraries in adapter layers.
• Isolate third-party dependencies to protect against change.
• Write tests that capture your expectations for external systems.