Documentação em Go: escrevendo código que fala por si só

Por que a documentação em Go é um superpoder, e não uma obrigação chata

Imagine: você abre um projeto Go de outra pessoa e lá — nenhum comentário. Funções chamadas f1, f2, e estruturas chamadas Data e MoreData. Familiar? Se sim, você sabe como o entusiasmo rapidamente se transforma em vontade de fechar o repositório.

Go é uma linguagem que adora simplicidade e clareza. Mas mesmo o código mais limpo nem sempre fala por si só. Uma boa documentação em Go não é apenas um "gesto de gentileza" para os colegas. É uma ferramenta profissional que:

\n
• Acelera a integração de novos desenvolvedores;
\n
• Ajuda a evitar bugs (lembra-se de que comentários podem salvar de um uso incorreto da API?);
\n
• Gera automaticamente páginas bonitas em pkg.go.dev;
\n
• Melhora a qualidade do código (tente escrever um comentário para uma função ruim — você mesmo vai querer reescrevê-la).
\n

Neste artigo, vamos abordar as melhores práticas de documentação de projetos Go. Desde as regras básicas do godoc até exemplos reais que você pode aplicar hoje mesmo. Vamos lá!

A filosofia da documentação em Go: menos palavras — mais significado

Go não é Java nem Python. Aqui, ninguém escreve Javadoc de várias páginas ou docstrings de 20 linhas. A filosofia do Go é simples: documente o comportamento, não a implementação.

No guia oficial Effective Go está claramente dito: os comentários devem descrever o que o código faz, não como. Se o seu código é tão complexo que precisa de uma explicação do algoritmo — talvez ele deva ser simplificado.

Princípios básicos:

\n
• O comentário é uma frase. Comece com o nome da função ou tipo. // Calculate returns the result of the calculation. — ótimo. // This function calculates... — perde o foco.
\n
• Escreva em inglês. Go é uma linguagem internacional, e a documentação em inglês é o padrão de fato. Mas se o seu projeto é estritamente para uma equipe de língua portuguesa, pode ser em português. O importante é a consistência.
\n
• Não explique o óbvio. // SetName sets the name — inútil. Melhor: // SetName updates the user's display name. Must be called before Save.
\n

Godoc: seu melhor amigo e documentador automático

Go vem com a ferramenta embutida godoc. Ela analisa os comentários diretamente do código e cria documentação HTML. Isso significa que sua documentação vive junto com o código — e é atualizada simultaneamente.

Como funciona? Muito simples. Escreva um comentário imediatamente antes da entidade exportada (função, tipo, estrutura, constante) — e o godoc o capturará.

Exemplo de pacote básico:

// Package calculator provides basic arithmetic operations.\npackage calculator\n\n// Add returns the sum of two integers.\nfunc Add(a, b int) int {\n    return a + b\n}\n\n// Subtract returns the difference of two integers.\nfunc Subtract(a, b int) int {\n    return a - b\n}

Agora execute godoc -http :8080 e abra o navegador. Você verá uma página bonita com a descrição do pacote e de cada função. Magia!

Regras de boa conduta para o godoc

\n
• Sempre comente o pacote. O comentário do pacote é a primeira coisa que o usuário vê. Ele deve descrever o propósito do pacote e, idealmente, conter um exemplo de uso.
\n
• Não se esqueça dos tipos e estruturas. Se a estrutura tem campos que não são óbvios pelo nome, documente-os também.
\n
• Use uma linha em branco. O godoc interpreta o primeiro parágrafo como uma descrição breve e o restante como detalhes. Separe-os com uma linha em branco.
\n

// User repre