80 lines
3.0 KiB
Markdown
80 lines
3.0 KiB
Markdown
# 🧹 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?
|