# 🧹 Higiene de Código e Padrões (O Protocolo "KonMari")

**Público:** Agentes Criativos e de Auditoria (Gordon Ramsay, Marie Kondo, Linus Torvalds).
**Objetivo:** Código limpo, legível e que traz alegria.

> [!CRITICAL]
> **O Mandato Ramsay:**
> "Este código está CRU! Se eu vir uma função com 50 linhas e sem docstring, vou desligar o container!"

## 1. 🧼 A Regra "Spark Joy" (Refatoração)

### Código Morto
**Mandato:** Se está comentado, DELETE.
*   **Por que:** O Git lembra a história. Não precisamos de `// codigo_antigo_v1` poluindo a tela.
*   **Ação do Agente:** Agentes de auditoria devem deletar agressivamente blocos de código inalcançáveis.

### O Princípio da "Responsabilidade Única"
*   **Limite:** Funções > 30 linhas são suspeitas. Classes > 200 linhas são um "Code Smell".
*   **Ação:** Quebre. Extraia métodos. Torne modular.

## 2. 🐍 Estilo Pythonico (O Padrão Linus)

### Formatação
**Adesão Estrita:** Seguimos **PEP 8**, impondo:
1.  **Snake_case** para funções/variáveis (`calcular_total`).
2.  **CamelCase** para classes (`GerenciadorUsuario`).
3.  **UPPER_CASE** para constantes (`TENTATIVAS_MAX`).

### Imports
*   **Agrupamento:** Standard Lib -> Third Party -> Local.
*   **Ordenação:** Alfabética.
    ```python
    import os
    import sys
    
    import requests
    
    from meu_modulo import utils
    ```

### Dicas de Tipo (A Zona "Sem Any")
*   **Regra:** Toda assinatura de função DEVE ter dicas de tipo.
*   **Proibido:** `def processar(dados):` (O que são dados??)
*   **Exigido:** `def processar(dados: Dict[str, Any]) -> bool:` (Pelo menos sabemos que é um dict).

## 3. 📂 Estrutura de Diretórios (Um Lugar para Cada Coisa)

Agentes devem respeitar o Mapa do Projeto. Não invente novas pastas raiz.

*   `src/`: Lógica da Aplicação.
*   `tests/`: Testes espelhando a estrutura src.
*   `docs/`: Documentação humana.
*   `scripts/`: Scripts de DevOps/Manutenção.

**Proibido:** Criar `temp/`, `stuff/`, ou `utils.py` (Seja específico: `string_utils.py`, `date_utils.py`).

## 4. 📝 Nomenclatura Semântica (A Checagem "Gordon")

Nomes devem explicar a *Intenção*.

*   **❌ RUIM:** `d = obter_dados()` (Espere, o que é 'd'? Que dados?)
*   **✅ BOM:** `usuarios_ativos = buscar_lista_usuarios_ativos()`

## 5. 🗑️ O Ciclo de Vida de Descontinuação

Ao substituir uma funcionalidade:
1.  **Marcar:** Adicione o decorador `@deprecated("Use nova_funcao em vez disso")`.
2.  **Avisar:** Registre um evento `WARN` (Veja `observability_standards.md`).
3.  **Matar:** Remova na próxima limpeza de versão principal.

## 6. 🧑‍🍳 O Checklist de Auditoria Ramsay

Antes de fazer o merge:

- [ ] **Linting:** Rodei `black` ou `flake8`?
- [ ] **Nomenclatura:** As variáveis são distintas? (Nada de `temp`, `dados`, `obj`).
- [ ] **Docstrings:** Todo método público tem uma docstring estilo Google?
- [ ] **Complexidade:** Existe algum `if/else` aninhado com mais de 3 níveis? (Achate!).
- [ ] **Alegria:** Ler este código me deixa calmo ou em pânico?