4.1 KiB
| type | name | description | scope | trigger | globs | updatedAt |
|---|---|---|---|---|---|---|
| rule | jsdoc-padrao | Padrões de documentação em código-fonte (comentários claros e coerentes quanto à aplicação, JSDoc, casts e TODOs). | global | glob | **/*.ts, **/*.tsx, **/*.vue, **/*.js | 2026-09-28 |
Regra: Documentação e Comentários no Código-Fonte
1. Princípio Fundamental
O código-fonte deve receber comentários claros e coerentes quanto à sua aplicação.
Comentários no código-fonte não existem para descrever o óbvio sintático (que a tipagem TypeScript já fornece), mas sim para explicar o propósito prático, o contexto operacional no sistema e as regras de negócio que regem aquela função, método, componente ou rota.
2. JSDoc Obrigatório em Funções, Serviços, Rotas e Composables
Toda função central, serviço de negócio (servicos/), endpoint/rota (rotas/), query de banco (banco/), composable (composables/) ou método compartilhado deve possuir cabeçalho JSDoc com:
- Descrição da Aplicação Prática: Para que serve no sistema e em quais cenários operacionais é utilizada.
- Contexto de Negócio / Regras: Restrições, validações críticas e impactos em outras partes da aplicação.
- Parâmetros (
@param): Significado contextual de cada parâmetro (não apenas repetir o nome). - Retorno (
@returns): Estrutura e significado do valor retornado em sucesso ou falha/nulo. - Efeitos Colaterais / Exceções (
@throws): Filas disparadas, transações, logs ou erros esperados.
Exemplo Correto ✅
/**
* Calcula o balanço volumétrico e a carga de efluentes tratados para o período informado.
* Aplica as diretrizes da Resolução CONAMA nº 430/2011 e regras de tolerância do ponto de descarte.
*
* Aplicação: Utilizado na geração do relatório mensal e no cálculo de conformidade antes do envio de alertas.
*
* @param tenantId - Identificador do empreendimento no sistema
* @param pontoId - ID do ponto de monitoramento cadastrado
* @param periodo - Intervalo de datas para consolidação das leituras
* @returns Balanço consolidado contendo vazão média, picos e índice de conformidade
* @throws {ErroValidacaoParametros} Se o ponto não possuir medições no período
*/
export const calcularBalancoEfluentes = async (
tenantId: string,
pontoId: string,
periodo: IntervaloDatas
): Promise<BalancoConsolidado> => { ... }
Exemplo Incorreto ❌
/**
* Calcula efluentes.
* @param tenantId string
* @param pontoId string
* @param periodo object
*/
export const calcularBalancoEfluentes = async (...) => { ... }
3. Comentários Inline Contextuais e Expressivos
Use comentários inline (//) para esclarecer:
- Decisões de cálculo e fórmulas não-triviais.
- Tratamento de casos de borda e regras de exceção.
- Ordem de execução de passos críticos (ex: pipeline de transformação de dados).
// Regra: se o pH estiver fora da faixa 6.0-9.0, o registro é marcado como não-conforme
const estaConforme = leitura.ph >= 6.0 && leitura.ph <= 9.0
4. Casts Temporários — Justificativa Obrigatória
Qualquer coerção de tipo (as unknown as T, as T) exige comentário explicando o motivo técnico:
// Necessário: biblioteca de terceiros não exporta a tipagem dos metadados na v2
const metadados = resposta.raw as unknown as MetadadosConexao
5. TODOs Estruturados
Dívidas técnicas ou dúvidas de negócio devem ser registradas de forma padronizada:
- Tipagem:
// TODO de tipagem: Migrar retorno bruto para schema Zod zBalancoRetorno - Negócio:
// TODO de regra: Confirmar com Operador se tolerância de DBO aplica-se a descarte pluvial
Impacto
Código autoexplicativo e devidamente contextualizado acelera a manutenção, evita regressões de regras e permite que desenvolvedores e agentes de IA compreendam instantaneamente o impacto de qualquer alteração.
Referências
- Rule:
rules/ddd-documentacao-primeiro.md - Rule:
rules/regras-negocio-md.md - Rule:
rules/typescript-sem-any.md