58 lines
3.2 KiB
Markdown
58 lines
3.2 KiB
Markdown
---
|
||
description: Workflow para criação e padronização de documentação em código (JSDoc, comentários e tipagem)
|
||
---
|
||
|
||
# Workflow: Documentar Código
|
||
|
||
## 🎯 Objetivo
|
||
Estabelecer um padrão global e unificado para a redação de documentação em código (comentários, `JSDoc` e explicações arquiteturais) em todas as aplicações, garantindo clareza sem prolixidade e respeitando a política de tipagem explícita.
|
||
|
||
---
|
||
|
||
## 1️⃣ Princípios Básicos de Documentação
|
||
- **Por que, não o Quê**: Documente o raciocínio por trás da decisão arquitetural ou a regra de negócio que forçou a estratégia, não o mecanismo óbvio que o TypeScript nativamente expressaria.
|
||
- **Nomenclatura Limpa**: Confie na auto-documentação de nomes de variáveis expressivos baseados no domínio antes de escrever um comentário de texto livre.
|
||
|
||
## 2️⃣ Funções Compartilhadas e JSDoc (Obrigatória)
|
||
Toda função central ou de uso compartilhado, independente da aplicação (frontend, backend, mobile ou bibliotecas comuns), deve portar cabeçalho em `JSDoc`.
|
||
|
||
### Padrão para JSDoc
|
||
```typescript
|
||
/**
|
||
* Busca os detalhes de uma entidade baseando-se no ID fornecido e calcula privilégios aplicáveis.
|
||
* Não utilizar em fluxos de processamento em lote para evitar sobrecarga de requisições ou banco.
|
||
*
|
||
* @param tenantId - Identificador único do cliente/tenant no sistema
|
||
* @param entityId - ID exclusivo identificando o registro na base de dados
|
||
* @returns Retorna o objeto consolidado com dados ou `null` caso não seja encontrado
|
||
*/
|
||
export const obterDetalhesEntidade = async (tenantId: string, entityId: string) => { ... }
|
||
```
|
||
|
||
## 3️⃣ Tratamento de Exceções e Casts Temporários
|
||
Devido à política `TypeScript sem any`, não utilizamos conversores obscuros imperativamente.
|
||
Porém, se uma coerção agressiva (`as unknown as X`) demonstrar-se temporariamente necessária por divergência ou limitação de SDK terceiro, **o comentário justificando a anomalia é obrigatório**.
|
||
|
||
```typescript
|
||
// Necessário cast duplo pois a biblioteca externa não provê tipagem genérica adequada na versão atual
|
||
const dados = payload.raw as unknown as RespostaFormatada
|
||
```
|
||
|
||
## 4️⃣ Atribuição de TODOs
|
||
Toda refatoração, debito técnico visualizado ou dúvida de negócio deixada aberta em código de longo prazo **não prescreve** e deve ser acompanhada do formato `// TODO`:
|
||
- **Tipagem**: `// TODO de tipagem: Criar interface estrita para o retorno da API de listagem (Removendo Partial)`
|
||
- **Negócio**: `// TODO de regra: Validar com a equipe de Produto se a nova taxa adicional será inserida para clientes antigos.`
|
||
|
||
## 5️⃣ Validação do Fluxo
|
||
Sempre ao propor documentação de um arquivo novo ou refatorado, valide via checklist:
|
||
* [ ] A documentação está aderente sem estar redundante à tipagem TS?
|
||
* [ ] A formatação de parágrafos/espaçamento quebra alguma regra no formatador?
|
||
* [ ] A sintaxe suporta autocompletion na sua camada dependente (`@params` estão exatos)?
|
||
|
||
---
|
||
|
||
## Referências
|
||
|
||
- Rules: `.agent/rules/typescript-sem-any.global.md` (política de tipagem que influencia a documentação)
|
||
- Skill: `.agent/skills/documentar-decisao-tecnica/SKILL.md` (para decisões arquiteturais que exigem ADR além de JSDoc)
|
||
|