minions-ai-agents/antigravity_brain_export/knowledge/code_hygiene_standards.md

🧹 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.

  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?