3.2 KiB
| 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
/**
* 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.
// 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 (
@paramsestã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)