Documentação em JavaScript: como escrever código que fala por si

Por que a documentação não é uma obrigação chata, mas um superpoder do desenvolvedor

Imagine: você abre um projeto JavaScript de outra pessoa (ou seu próprio projeto de três meses atrás). Os arquivos estão cheios de arrow functions, async/await e desestruturação. Mas por que essa função se chama transformData? O que ela recebe? E o principal — para que ela serve, se ao lado existe processArray?

Se você já se pegou pensando: "Não me lembro o que está acontecendo aqui", — este artigo é para você. Documentação em JavaScript não é sobre parágrafos chatos de texto. É sobre respeito ao seu eu futuro e aos seus colegas. É sobre velocidade de entrada no projeto e redução de bugs. Neste artigo, vamos abordar as melhores práticas de documentação de código JS: desde JSDoc até a geração de documentação completa.

Documentação de código JavaScript: a filosofia do "código que fala"

Antes de escrever comentários, é importante entender: o melhor comentário é aquele que não é necessário. O código ideal deve se explicar por si só. Como conseguir isso?

Nomeação de variáveis e funções

Exemplo ruim:

// Ruim\nconst x = 10; // o que é x?\nfunction d(a, b) { return a * b; } // o que d faz?\n

Exemplo bom:

// Bom\nconst MAX_RETRY_COUNT = 10;\nfunction calculateDiscountedPrice(price, discountPercent) {\n  return price * (1 - discountPercent / 100);\n}\n

Use nomes completos e significativos. Nomeie funções com verbos (getUser, validateEmail), variáveis com substantivos (userList, isActive). Esta é a base do código autodocumentado.

Quando os comentários ainda são necessários

\n
• Lógica de negócios complexa: por exemplo, cálculo de impostos com uma fórmula não óbvia.
\n
• Gambiarras ou soluções temporárias: marque com TODO ou FIXME.
\n
• Por que esta abordagem foi escolhida: alternativas existiam, mas esta é a ideal em termos de velocidade.
\n
• Descrição de API pública: para que outros desenvolvedores saibam como chamar sua função.
\n

JSDoc: o padrão de documentação JavaScript

JSDoc é uma sintaxe para escrever documentação diretamente no código, que é compreendida por editores (VS Code, WebStorm) e ferramentas de geração. É um must-have para qualquer projeto sério.

Anotação básica de função

/**\n * Calcula o valor total do pedido com desconto e imposto.\n * @param {number} price - Preço base do produto.\n * @param {number} discount - Desconto em porcentagem (0-100).\n * @param {number} taxRate - Taxa de imposto em porcentagem (0-100).\n * @returns {number} Valor total.\n */\nfunction calculateTotal(price, discount, taxRate) {\n  const discountedPrice = price * (1 - discount / 100);\n  return discountedPrice * (1 + taxRate / 100);\n}\n

Agora, ao passar o mouse sobre a função calculateTotal no editor, você verá sua descrição, parâmetros e valor de retorno. Mágica!

Anotações para objetos e tipos

/**\n * @typedef {Object} User\n * @property {number} id - Identificador único.\n * @property {string} name - Nome do usuário.\n * @property {boolean} isActive - Se a conta está ativa.\n */\n\n/**\n * Obtém a lista de usuários ativos.\n * @param {User[]} users - Array de usuários.\n * @returns {User[]} Array filtrado.\n */\nfunction getActiveUsers(users) {\n  return users.filter(user => user.isActive);\n}\n

O uso de @typedef permite criar tipos personalizados, tornando o código legível e seguro. Isso é especialmente útil em projetos sem TypeScript.

Documentação de funções assíncronas

/**\n * Carrega os dados do usuário do servidor.\n * @async\n * @param {number} userId - ID do usuário.\n * @returns {Prom