modular-code

# Modular Code Organization Write modular Python code with files sized for maintainability and AI-assisted development. ## File Size Guidelines | Lines | Status | Action | |-------|--------|--------| | 150-500 | Optimal | Sweet spot for AI code editors and human comprehension | | 500-1000 | Large | Look for natural split points | | 1000-2000 | Too large | Refactor into focused modules | | 2000+ | Critical | Must split - causes tooling issues and cognitive overload | ## When to Split Split when ANY of these apply: - File exceeds 500 lines - Multiple unrelated concerns in same file - Scroll fatigue finding functions - Tests for the file are hard to organize - AI tools truncate or miss context ## How to Split ### Natural Split Points 1. **By domain concept**: `auth.py` → `auth/login.py`, `auth/tokens.py`, `auth/permissions.py` 2. **By abstraction layer**: Separate interface from implementation 3. **By data type**: Group operations on related data structures 4. **By I/O boundary**: Isolate database, API, file operations ### Package Structure ``` feature/ ├── __init__.py # Keep minimal, just exports ├── core.py # Main logic (under 500 lines) ├── models.py # Data structures ├── handlers.py # I/O and side effects └── utils.py # Pure helper functions ``` ## DO - Use meaningful module names (`data_storage.py` not `utils2.py`) - Keep `__init__.py` files minimal or empty - Group related functions together - Isolate pure functions from side e...