João Henrique
b2a8b1f24c
criado repositório jhonny-editor no Gitea adicionado script admin/deploy.command com commit automático atualizado admin/DEV-NOTES.md com template limpo Resumo: - 8 arquivos alterados - 2 novos - 6 modificados - 0 removidos 6 files changed, 33 insertions(+), 3 deletions(-) Arquivos: - .agents/skills/boas-praticas-oo/SKILL.md - .claude/settings.json - AGENTS.md - CLAUDE.md - CODING_STANDARDS.md - code/engine/executar_scanner.py - .claude/hooks/ - code/engine/testes/test_executar_scanner.py
68 lines
4.5 KiB
Markdown
68 lines
4.5 KiB
Markdown
# 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 **`.agents/skills/boas-praticas-oo/SKILL.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. |