# Guia de Referência: Código Limpo (Robert C. Martin)

Este guia concentra as práticas de código limpo em regras para IA: o código deve comunicar intenção, manter unidades pequenas e coesas, controlar efeitos colaterais, tratar erros de forma explícita e ser sustentado por testes e refatoração contínua.

---

## 1. Nomes Significativos

* **Intenção:** Nomes devem explicar por que algo existe, o que faz e como é usado.
* **Precisão:** Evite nomes genéricos, enganadores, abreviações obscuras e diferenças irrelevantes.
* **Vocabulário:** Use termos consistentes do domínio e do projeto para conceitos equivalentes.

---

## 2. Funções

* **Pequenas e focadas:** Funções devem fazer uma coisa em um nível de abstração coerente.
* **Argumentos:** Prefira poucos argumentos; muitos parâmetros podem sinalizar objeto/abstração ausente.
* **Efeitos colaterais:** Evite fazer algo inesperado além do que o nome e contrato prometem.
* **Comandos e consultas:** Quando possível, separe operações que mudam estado das que apenas retornam informação.

---

## 3. Comentários e Formatação

* **Código primeiro:** Prefira tornar o código autoexplicativo a usar comentário para compensar estrutura confusa.
* **Comentários úteis:** Documente intenção, decisões, riscos ou contexto que o código não consegue expressar sozinho.
* **Formatação:** Organização visual e proximidade ajudam o leitor a reconhecer relações e níveis de abstração.

---

## 4. Objetos, Estruturas e Erros

* **Encapsulamento:** Objetos protegem invariantes e oferecem comportamento; estruturas de dados expõem dados deliberadamente.
* **Demeter:** Evite cadeias longas de conhecimento entre objetos quando isso cria acoplamento excessivo.
* **Exceções:** Use exceções/erros para separar fluxo normal de tratamento de falhas quando a linguagem/ecossistema favorecer isso.
* **Null:** Reduza a necessidade de `null` em contratos quando valores opcionais, objetos nulos ou tipos explícitos tornarem o código mais seguro.

---

## 5. Testes Limpos

* **Legibilidade:** Código de teste precisa ser tão compreensível e mantido quanto o de produção.
* **Um conceito:** Cada teste deve comunicar um comportamento/expectativa principal.
* **Rápidos e independentes:** Testes de unidade devem fornecer feedback rápido e evitar dependências entre si.
* **Repetibilidade:** Resultados não devem depender de ordem, relógio, rede ou estado externo sem controle.

---

## 6. Classes e Sistemas

* **Responsabilidade:** Classes devem ter razões coesas para mudar.
* **Organização:** Separe construção/configuração da lógica de negócio; concentre wiring no ponto de composição.
* **Evolução:** Use refatoração contínua para melhorar nomes, remover duplicação e manter o design compreensível.
* **Simplicidade:** Evite estruturas desnecessárias e prefira soluções que revelem intenção.

---

## 7. Como Usar com IA

Anexe este arquivo a qualquer implementação ou revisão. Peça que a IA aplique as regras como checklist: nomes, funções, efeitos colaterais, tratamento de erro, testes, duplicação e responsabilidades.

---

## Diretrizes de Execução para IA

Ao criar, revisar ou reestruturar uma aplicação, garanta:

1.  **Escreva para leitores humanos** e revele intenção no código.
2.  **Mantenha unidades pequenas e coesas**.
3.  **Trate falhas explicitamente** e evite efeitos colaterais escondidos.
4.  **Mantenha testes limpos e confiáveis**.
5.  **Refatore continuamente** para remover duplicação e melhorar estrutura.


---

## Roteiro de Uso Operacional com IA

1. **Contextualize o projeto:** informe domínio, stack, arquitetura atual, restrições e objetivo da mudança.
2. **Selecione o recorte:** diga qual princípio/capítulo deste guia deve orientar a tarefa; não aplique tudo ao mesmo tempo.
3. **Peça diagnóstico antes do código:** a IA deve identificar sintomas, riscos, dependências e alternativas.
4. **Defina critérios de aceite:** comportamento, testes, acessibilidade, performance, segurança ou operação conforme o tema.
5. **Implemente incrementalmente:** mudanças pequenas, reversíveis e verificadas.
6. **Faça revisão final:** peça à IA que confronte a solução com este guia e liste desvios deliberados.

### Prompt de aplicação

```text
Use este guia como referência técnica para a tarefa abaixo.
Não copie regras mecanicamente. Primeiro diagnostique o problema e selecione apenas os princípios aplicáveis.
Mostre: (1) diagnóstico, (2) decisão, (3) implementação proposta, (4) testes/verificações, (5) trade-offs e (6) checklist final.

Contexto: [DESCREVA o sistema, stack, estado atual e cenário da mudança]
Objetivo: [DESCREVA o resultado esperado e o comportamento que deve existir]
Restrições: [DESCREVA limites de escopo, compatibilidade, segurança, prazo e o que não pode mudar]
```


### Como preencher os campos

- **Contexto:** descreva o tipo de sistema, stack/versões, arquitetura atual, onde a mudança acontece e o comportamento relevante já existente.
- **Objetivo:** descreva o resultado observável que deve existir ao final, não apenas a tecnologia que você quer usar.
- **Restrições:** informe o que não pode mudar, compatibilidade, prazo, segurança, acessibilidade, performance, legado, dependências e limites de escopo.

### Exemplo preenchido

```text
Contexto: Módulo JavaScript funciona, porém possui funções extensas, variáveis genéricas e comentários explicando trechos difíceis.
Objetivo: Melhorar clareza do código sem alterar comportamento, priorizando nomes, funções coesas e remoção de duplicação.
Restrições: Não aplicar regras de estilo mecanicamente; preservar performance necessária e APIs públicas; mudanças devem ser verificadas por testes.
```