# Padrões de código

Este documento consolida as convenções obrigatórias de código do projeto. Serve de fonte de verdade para revisões automáticas (eixo *Standards* do `/code-review`) e vale para qualquer agente que escreva ou altere código.

A fonte completa das regras de orientação a objeto é a skill **`code/engine/skills/boas-praticas-oo.md`**. O que está abaixo é o resumo normativo; em caso de dúvida, leia a skill por inteiro.

## Escopo

As regras de PT-BR e OO aplicam-se a todo **Python em `code/engine/`**. Outras linguagens seguem as convenções existentes no repositório, mas os princípios de design (responsabilidade única, baixo acoplamento, injeção de dependência, módulos profundos) são universais.

## Idioma — PT-BR obrigatório

Todos os identificadores internos usam português brasileiro:

- Classes, métodos, funções, variáveis, atributos, parâmetros, constantes, arquivos, pastas e módulos.
- Docstrings, comentários, logs, mensagens de erro e documentação.
- Nomes de testes, fixtures e exemplos.

Identificadores **externos** (bibliotecas, APIs, endpoints, campos de contrato, variáveis de ambiente de terceiros, protocolos) são preservados no idioma oficial **somente quando exigidos**, e isolados em adaptadores/conversores/clientes/repositórios. Não espalhar nomes externos pelo sistema; converter na fronteira para o modelo interno em PT-BR e documentar a exceção.

## Nomenclatura

- Classes: `PascalCase` — ex. `GerenciadorDeArquivos`.
- Métodos, funções, variáveis, atributos, arquivos e pastas: `snake_case` — ex. `carregar_arquivo`, `nome_do_usuario`.
- Constantes: `MAIÚSCULAS_COM_SUBLINHADO` — ex. `TEMPO_LIMITE_DA_OPERACAO`.
- Evitar nomes genéricos: `Util`, `Helper`, `Manager`, `Processor`, `Data`, `Object`, `Thing`, `Temp`.

## Documentação

- Todo **módulo** tem docstring no topo: finalidade, problema que resolve, responsabilidade, o que não faz, componentes e dependências principais.
- Toda **classe** tem docstring: o que representa, responsabilidade, dependências, o que não deve fazer, efeitos colaterais quando aplicável.
- Todo **método/função público** tem docstring: o que faz, dados que recebe, retorno, erros possíveis, se altera estado, se realiza operações externas.
- **Documentação viva**: docstring/comentário deve descrever o comportamento atual. Proibido manter documentação de comportamento que não existe mais.

## Design / orientação a objeto

- **Responsabilidade única**: cada classe/função/módulo tem uma responsabilidade principal.
- **Alta coesão**: métodos da classe relacionam-se à sua responsabilidade.
- **Baixo acoplamento**: depender do mínimo; receber dependências, não criá-las internamente.
- **Composição antes de herança**; herança apenas com relação real de "é um".
- **Encapsulamento**: dados e regras protegidos, alterados por operações apropriadas.
- **Interfaces pequenas** e **injeção de dependências** explícita.
- **Métodos pequenos e objetivos**; retornos previsíveis e consistentes.
- **Módulos profundos**: muita funcionalidade atrás de interface pequena (ver skill `codebase-design`).

## Domínio e integrações

- Regras de negócio ficam no **domínio/aplicação**, nunca na interface, em controladores gigantes, scripts, SQL, HTTP ou camada de apresentação.
- Integrações externas (APIs, banco, arquivos, serviços) isoladas em módulos próprios; o resto do sistema usa contratos/classes internas.
- Não duplicar regras: centralizar em classe, função, validador, objeto de valor ou constante.
- Evitar dependências circulares; resolver com contratos, módulo comum, inversão ou injeção de dependência.

## Erros e segurança

- Tratar erros com **exceções específicas**; nunca `except Exception: pass`.
- Validar toda entrada externa (tipo, formato, limites, nulos, estrutura) antes de usar.
- Não registrar senhas, tokens, chaves ou dados sensíveis em logs.
- Configurações em componentes próprios, não espalhadas no código.

## Testes

- Toda funcionalidade relevante tem testes (unitário, integração, regressão).
- Cobrir: entradas válidas/inválidas, casos vazios/extremos, erros, retornos, efeitos colaterais, regras de negócio.
- Ao corrigir bug, criar/atualizar teste que impeça regressão.

## Checklist antes de finalizar

Antes de dar como concluída qualquer implementação Python em `code/engine/`, percorrer a seção 41 da skill `boas-praticas-oo.md`: requisitos, arquitetura, código, documentação e testes.