103 lines
6.4 KiB
Markdown
103 lines
6.4 KiB
Markdown
---
|
|
type: workflow
|
|
name: codigo-limpo
|
|
description: Workflow oficial de Código Limpo e Refatoração baseado nas 12 Regras Canônicas (Dispatch Tables, SRP, DRY, Escoteiro)
|
|
scope: global
|
|
updatedAt: "2026-09-16"
|
|
---
|
|
|
|
# Workflow: /codigo-limpo (Guia das 12 Regras de Código Limpo)
|
|
|
|
Workflow oficial de limpeza, refatoração e otimização de código para projetos TypeScript, Vue 3, TSX e JSX no ecossistema Azteca.
|
|
|
|
> 💡 **Comando rápido:** Execute `/codigo-limpo <arquivo_ou_modulo>` para inspecionar, diagnosticar e refatorar o código sob as 12 regras canônicas. (Alias retrocompatível: `/otimizar-codigos`).
|
|
|
|
---
|
|
|
|
## As 12 Regras Canônicas do Código Limpo
|
|
|
|
### I. Nomenclatura e Clareza
|
|
|
|
1. **Nomes significativos e sem "Números Mágicos":**
|
|
Variáveis, funções e classes devem revelar explicitamente sua intenção. Substitua valores soltos (ex.: `status === 4` ou timeout `86400000`) por constantes ou enums tipados e legíveis (ex.: `status === STATUS_PAGO`, `TEMPO_EXPIRACAO_MS = 24 * HORA_MS`). O nome deve dispensar explicações secundárias.
|
|
|
|
2. **O código deve explicar a si mesmo:**
|
|
Evite comentários redundantes que apenas parafraseiam *o que* o código faz. Use comentários e JSDoc exclusivamente para explicar o *porquê* de uma decisão técnica complexa, regras de negócio ou referenciar a Wiki Dev (`wiki/dev/<modulo>/`). O código limpo é a única fonte real da verdade.
|
|
|
|
3. **Prefira Mapeamento (Dispatch Tables) a Switch/If-Else encadeados:**
|
|
Evite tripas de condicionais (`if/else if/else` ou `switch` volumosos). Sempre que associar chaves/status a ações, configurações ou componentes, crie um **Objeto de Mapeamento (Dispatch Table)** fortemente tipado:
|
|
- **Executar funções/ações:**
|
|
```ts
|
|
const acoesStatus: Record<StatusLicenca, (licenca: Licenca) => void> = {
|
|
[StatusLicenca.APROVADA]: emitirCertificado,
|
|
[StatusLicenca.PENDENTE]: solicitarDocumentos,
|
|
[StatusLicenca.CANCELADA]: arquivarProcesso,
|
|
}
|
|
acoesStatus[status]?.(licenca)
|
|
```
|
|
- **Retornar dados e configurações:**
|
|
```ts
|
|
const CONFIG_VARIANTE: Record<TipoAlerta, { cor: string; icone: Component }> = {
|
|
erro: { cor: 'var(--cor-eli-erro)', icone: AlertTriangle },
|
|
sucesso: { cor: 'var(--cor-eli-sucesso)', icone: CheckCircle2 },
|
|
}
|
|
```
|
|
- **Renderizar componentes (Vue/TSX):**
|
|
```vue
|
|
<component :is="mapaComponentes[tipoAtual]" :dados="dadosItem" />
|
|
```
|
|
|
|
### II. Funções e Métodos
|
|
|
|
4. **Funções devem ser pequenas:**
|
|
Uma função deve ter responsabilidade única: fazer apenas uma coisa, fazê-la bem, e fazer apenas ela. Se ultrapassar 25 a 30 linhas ou contiver múltiplos níveis de indentação, extraia blocos em funções auxiliares ou composables.
|
|
|
|
5. **Reduza o número de parâmetros:**
|
|
O ideal é que uma função receba zero, um ou no máximo dois argumentos. Caso precise de três ou mais parâmetros, agrupe-os em um **Objeto de Parâmetros tipado** via `interface`, `type` ou schema Zod (`interface FiltroParams { ... }`).
|
|
|
|
6. **Não crie efeitos colaterais (Side Effects Ocultos):**
|
|
Uma função não deve modificar estado global, mutar parâmetros recebidos ou alterar variáveis fora do seu escopo de forma oculta. Prefira funções puras e imutabilidade; o escopo da ação deve estar transparente em seu nome e tipo de retorno.
|
|
|
|
### III. Estrutura e Design
|
|
|
|
7. **Princípio DRY (Don't Repeat Yourself):**
|
|
Elimine duplicação lógica e estrutural. Se o mesmo trecho, cálculo ou padrão de interface existe em 2 ou mais lugares, transforme-o em uma função utilitária, composable (`use*.ts`), constante compartilhada ou componente reutilizável.
|
|
|
|
8. **Responsabilidade Única (SRP) e Limite de 250 Linhas:**
|
|
Uma classe, módulo ou componente deve ter apenas um motivo para mudar. Nunca misture acesso a banco de dados, regras de negócio e renderização de UI no mesmo arquivo.
|
|
- **Limite rígido:** Nenhum arquivo pode ultrapassar **250 linhas** (`verificar-linhas.sh`).
|
|
- Se um componente crescer, desmembre em pasta com `index.vue` + `SecaoX.vue` + `*.mapeadores.ts` + `*.css`.
|
|
|
|
9. **Formatação e Padronização Automatizada:**
|
|
O código do projeto deve parecer ter sido escrito por uma única pessoa. Sempre valide a formatação com o Biome (`biome check --write`), respeitando aspas simples, sem ponto e vírgula supérfluo, indentação de 2 espaços e regras de lint estritas.
|
|
|
|
### IV. Tratamento e Qualidade
|
|
|
|
10. **Trate erros com elegância e visibilidade:**
|
|
Nunca silencie erros com blocos `catch` vazios (`catch (_) {}`). Sempre registre contexto técnico suficiente (`console.error`) e exiba feedback compreensível ao usuário via Toast/Banner (ver `feedback-visivel.md`). Lance exceções semânticas ou retorne tipos Result discriminados em vez de `-1` ou `null` arbitrário.
|
|
|
|
11. **Testes devem ser limpos e independentes:**
|
|
Código de teste é cidadão de primeira classe. Cada teste deve focar em um único cenário, rodar rápido, ser determinístico e nunca depender do resultado ou ordem de execução de outro teste.
|
|
|
|
12. **A Regra do Escoteiro:**
|
|
*"Deixe a área de acampamento mais limpa do que como a encontrou."* Toda vez que abrir um arquivo para corrigir um bug ou criar uma funcionalidade, faça ao menos uma melhoria estrutural: remova um import inútil, renomeie uma variável críptica, extraia uma constante ou desfaça uma condicional encadeada.
|
|
|
|
---
|
|
|
|
## Protocolo de Execução do /codigo-limpo
|
|
|
|
Quando o workflow for acionado, siga as etapas:
|
|
|
|
```
|
|
1. DIAGNOSTICAR ──▶ 2. PLANEJAR ──▶ 3. EXECUTAR ──▶ 4. VALIDAR ──▶ 5. ENTREGAR
|
|
(12 Regras) (Decomposição) (Cirúrgico) (Biome/Tests) (Relatório)
|
|
```
|
|
|
|
1. **Diagnosticar:** Inspecione o código-alvo mapeando cada violação entre as 12 regras (ex.: `status == 2` sem constante, `if/switch` encadeado, funções > 30 linhas, arquivo > 250 linhas).
|
|
2. **Planejar:** Defina a estrutura de arquivos e despacho. Não quebre contratos de API, props de componentes ou regras de negócio.
|
|
3. **Executar:** Refatore passo a passo, substituindo condicionais por Dispatch Tables e extraindo composables/helpers conforme necessário.
|
|
4. **Validar:**
|
|
- Execute `biome check --write <arquivos>` para formatar.
|
|
- Valide limite de linhas: `sh .agent/verificar-linhas.sh`.
|
|
- Assegure tipagem estrita (zero `any`).
|
|
5. **Entregar:** Apresente os problemas encontrados, as regras aplicadas e o código final refatorado pronto para uso.
|