Convenções de Documentação & godoc
Comentários de pacote, exemplos e playbooks internos.
//
Busque em todas as páginas da documentação
Comentários de pacote, exemplos e playbooks internos.
A documentação Go são comentários interpretados por go doc e pkg.go.dev.
Equipes que tratam a documentação como parte da API reduzem o atrito no onboarding, melhoram a qualidade das revisões e tornam o material de referência gerado confiável.
godoc é a superfície de referência padrão para pacotes Go.
Comentários de pacote explicam o propósito e os padrões de uso.
Comentários de símbolo documentam o comportamento, regras de concorrência e semântica de erros.
Exemplos fornecem trechos executáveis.
Playbooks internos cobrem runbooks e etapas de onboarding que o godoc não deve tentar conter.
Cartão de receita de referência rápida - pronto para copiar e colar.
// Package ratelimit fornece limitação de taxa de token-bucket para manipuladores HTTP.
//
// Use NewLimiter na inicialização do processo e compartilhe um único Limiter entre os manipuladores.
// Limiter são seguros para uso concorrente.
package ratelimit
// Limiter controla a taxa de requisições usando um token bucket.
type Limiter struct { /* ... */ }
// Allow reporta se um evento pode prosseguir no tempo now.
// É seguro para uso concorrente por múltiplas goroutines.
func (l *Limiter) Allow(now time.Time) bool { /* ... */ }Quando usar isso:
Uma biblioteca adiciona documentação executável e uma visão geral do pacote.
// example_test.go
package ratelimit_test
import (
"fmt"
"time"
"example.com/lib/ratelimit"
)
func ExampleNewLimiter() {
lim := ratelimit.NewLimiter(10, time.Second)
ok := lim.Allow(time.Now())
fmt.Println(ok)
// Output: true
}go test -run Example
go doc example.com/lib/ratelimitO que isso demonstra:
*_test.go com o prefixo Example e // Output: opcional.go test executa exemplos como testes; exemplos quebrados falham o CI.Limiter.package (apenas um arquivo por pacote deve carregar o bloco principal).| Elemento | Regra |
|---|---|
| func/type/const Exportado | Comentário começa com o nome; declara o que faz |
| Erros | Documenta condições de retorno e retentabilidade |
| Contexto | Nota efeitos de cancelamento |
| Concorrência | Declara explicitamente se é seguro/inseguro |
| Valor zero | Diz se o valor zero é útil |
| Depreciado | // Deprecated: use NewX em vez disso |
// Ruim - comentário não começa com o nome do símbolo
// Retorna um limiter para controle de taxa.
func NewLimiter(rate int, window time.Duration) *Limiter
// Bom
// NewLimiter retorna um Limiter que permite 'rate' eventos por 'window'.
func NewLimiter(rate int, window time.Duration) *Limiter// ErrRateExceeded indica que o cliente excedeu a cota.
// Chamadores podem tentar novamente após a duração RetryAfter.
var ErrRateExceeded = errors.New("taxa excedida")Linke tipos relacionados com nomes de texto simples; godoc auto-linka identificadores quando possível.
doc.go ou arquivo designado por pacote.httptest.Server com saída determinística.| Alternativa | Use Quando | Não Use Quando |
|---|---|---|
| Apenas README | Ferramentas de linha de comando internas | Bibliotecas exportadas consumidas por outras equipes |
| OpenAPI para HTTP | Superfície REST é o contrato principal | Bibliotecas puramente Go sem HTTP |
| Comentários Protobuf | gRPC é a API principal | Funções auxiliares Go escritas manualmente ainda precisam de godoc |
| Docs gerados (swaggo) | Grande superfície HTTP | Você ainda precisa de comentários de nível de pacote Go para lógica |
Documente itens não exportados quando a complexidade exigir, mas o godoc não os mostrará no pkg.go.dev. Prefira nomes claros para internos.
Uma a três sentenças para a maioria dos símbolos. Prose mais longa pertence ao comentário do pacote ou a documentos de design em markdown linkados a partir do README.
Nomes de testes e casos de tabela são documentação para colegas de equipe. Use funções Example quando quiser trechos para pkg.go.dev.
Adicione a linha Deprecated: com a substituição e o cronograma. Revisores bloqueiam novos usos de símbolos depreciados em código de aplicação.
Sim, quando as APIs precisam de genéricos ou novos símbolos da stdlib. Alinhe com a diretiva go do módulo em go.mod.
Corresponda à política da equipe. Idiomas misturados prejudicam a busca e o onboarding; a maioria das bases de código de produção padroniza em inglês para exports.
Execute go test para exemplos, opcionalmente go vet e linters que verificam sentenças de comentários em exports.
Os donos dos serviços rotacionam a revisão trimestral de links de README e runbooks; equipes de plataforma são donas de templates compartilhados.
ADRs registram o porquê; godoc registra o quê e como. Linke ADRs no README, não em cada comentário de função.
Autores devem verificar a precisão contra caminhos de código e erros. Revisores tratam godoc incorreto como um bug bloqueador.
go docVersões de Stack: Esta página foi escrita para Go 1.26.x (padrão Green Tea GC, go fix modernizers - verifique o patch na compilação), chi (latest - verifique na compilação), gin (latest - verifique na compilação), echo (latest - verifique na compilação), google.golang.org/grpc (latest - verifique na compilação), sigs.k8s.io/controller-runtime (latest - verifique na compilação), kubebuilder (latest - verifique na compilação), tinygo (latest - verifique os alvos de placa na compilação), wazero (latest - verifique na compilação), e golangci-lint (latest - verifique o conjunto de linters na compilação).
Revisado por Chris St. John·Última atualização: 16 de jul. de 2026