115 lines
4.1 KiB
Markdown
115 lines
4.1 KiB
Markdown
---
|
|
type: rule
|
|
name: jsdoc-padrao
|
|
description: Padrões de documentação em código-fonte (comentários claros e coerentes quanto à aplicação, JSDoc, casts e TODOs).
|
|
scope: global
|
|
trigger: file_match
|
|
globs:
|
|
- "**/*.ts"
|
|
- "**/*.tsx"
|
|
- "**/*.vue"
|
|
- "**/*.js"
|
|
updatedAt: "2026-09-01"
|
|
---
|
|
|
|
# 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:
|
|
|
|
1. **Descrição da Aplicação Prática**: Para que serve no sistema e em quais cenários operacionais é utilizada.
|
|
2. **Contexto de Negócio / Regras**: Restrições, validações críticas e impactos em outras partes da aplicação.
|
|
3. **Parâmetros (`@param`)**: Significado contextual de cada parâmetro (não apenas repetir o nome).
|
|
4. **Retorno (`@returns`)**: Estrutura e significado do valor retornado em sucesso ou falha/nulo.
|
|
5. **Efeitos Colaterais / Exceções (`@throws`)**: Filas disparadas, transações, logs ou erros esperados.
|
|
|
|
### Exemplo Correto ✅
|
|
|
|
```typescript
|
|
/**
|
|
* 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 ❌
|
|
|
|
```typescript
|
|
/**
|
|
* 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).
|
|
|
|
```typescript
|
|
// 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:
|
|
|
|
```typescript
|
|
// 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`
|