Maintainability Principles

Code MUST adhere to these maintainability requirements:

Code Structure

1. Single Responsibility - Functions and classes do ONE thing. Keep them focused and small.

1. DRY (Don't Repeat Yourself) - Extract common logic into reusable functions. Avoid copy-paste.

1. Separation of Concerns - Keep business logic, data access, and presentation separate.

Naming & Readability

1. Clear Naming - Variables, functions, and classes describe their purpose. Avoid abbreviations.

1. No Magic Numbers - Constants are named and explained. Avoid hardcoded values.

1. Consistent Style - Follow project conventions. Use consistent formatting and patterns.

Error Handling

1. Explicit Error Handling - All errors are caught and handled appropriately. No silent failures.

1. Meaningful Error Messages - Errors include context for debugging. Log relevant details.

1. Graceful Degradation - Handle edge cases. Provide fallbacks where appropriate.

Testing & Documentation

1. Testability - Code is unit-testable. Dependencies are injectable. Pure functions preferred.

1. Self-Documenting Code - Code is readable without comments. Complex logic has explanations.

1. API Documentation - Public APIs have clear documentation. Include examples.

Design

1. Loose Coupling - Minimize dependencies between modules. Use interfaces/abstractions.

1. High Cohesion - Related functionality is grouped together. Modules have clear boundaries.

1. YAGNI - Don't build for hypothetical future requirements. Solve current problems.

Checklist

When reviewing code, verify:

• Functions are small and focused
• No code duplication
• Clear, descriptive naming
• No magic numbers or strings
• Consistent code style
• Proper error handling
• Code is testable
• Complex logic is documented
• Dependencies are minimized
• No over-engineering