# 🧹 Code Hygiene & Standards (The "KonMari" Protocol)

**Audience:** Creative & Audit Agents (Gordon Ramsay, Marie Kondo, Linus Torvalds).
**Objective:** Code that is clean, readable, and sparks joy.

> [!CRITICAL]
> **The Ramsay Mandate:**
> "This code is RAW! If I see a function with 50 lines and no docstring, I am shutting down the container!"

## 1. 🧼 The "Spark Joy" Rule (Refactoring)

### Dead Code
**Mandate:** If it's commented out, DELETE IT.
*   **Why:** Git remembers history. We do not need `// old_code_v1` cluttering the screen.
*   **Agent Action:** Audit agents must aggressively delete unreachable code blocks.

### The "Single Responsibility" Principle
*   **Limit:** Functions > 30 lines are suspicious. Classes > 200 lines are a "Code Smell".
*   **Action:** Break it down. Extract methods. Make it modular.

## 2. 🐍 Pythonic Style (The Linus Standard)

### Formatting
**Strict Adherence:** We follow **PEP 8**, enforcing:
1.  **Snake_case** for functions/variables (`calculate_total`).
2.  **CamelCase** for classes (`UserManager`).
3.  **UPPER_CASE** for constants (`MAX_RETRIES`).

### Imports
*   **Grouping:** Standard Lib -> Third Party -> Local.
*   **Sorting:** Alphabetical.
    ```python
    import os
    import sys
    
    import requests
    
    from my_module import utils
    ```

### Type Hints (The "No Any" Zone)
*   **Rule:** Every function signature MUST have type hints.
*   **Forbidden:** `def process(data):` (What is data??)
*   **Required:** `def process(data: Dict[str, Any]) -> bool:` (At least we know it's a dict).

## 3. 📂 Directory Structure (A Place for Everything)

Agents must respect the Project Map. Do not invent new root folders.

*   `src/`: Application Logic.
*   `tests/`: Tests mirroring the src structure.
*   `docs/`: Human documentation.
*   `scripts/`: DevOps/Maintenance scripts.

**Forbidden:** Creating `temp/`, `stuff/`, or `utils.py` (Be specific: `string_utils.py`, `date_utils.py`).

## 4. 📝 Semantic Naming (The "Gordon" Check)

Names must explain the *Intent*.

*   **❌ BAD:** `d = get_data()` (Wait, what is 'd'? What data?)
*   **✅ GOOD:** `active_users = fetch_active_user_list()`

## 5. 🗑️ The Deprecation Lifecycle

When replacing a feature:
1.  **Mark:** Add `@deprecated("Use new_function instead")` decorator.
2.  **Warn:** Log a `WARN` event (See `observability_standards.md`).
3.  **Kill:** Remove in the next major version cleanup.

## 6. 🧑‍🍳 The Ramsay Audit Checklist

Before merging:

- [ ] **Linting:** Did I run `black` or `flake8`?
- [ ] **Naming:** Are variables distinct? (No `temp`, `data`, `obj`).
- [ ] **Docstrings:** Does every public method have a Google-style docstring?
- [ ] **Complexity:** Are there any nested `if/else` deeper than 3 levels? (Flatten it!).
- [ ] **Joy:** Does reading this code make me feel calm or panicked?