Documentation & godoc Conventions

Package comments, examples, and internal playbooks.

Go documentation is comments interpreted by go doc and pkg.go.dev.

Teams that treat docs as part of the API reduce onboarding friction, improve review quality, and make generated reference material trustworthy.

Summary

godoc is the default reference surface for Go packages.

Package comments explain purpose and usage patterns.

Symbol comments document behavior, concurrency rules, and error semantics.

Examples provide executable snippets.

Internal playbooks cover runbooks and onboarding steps godoc should not try to hold.

Recipe

Quick-reference recipe card - copy-paste ready.

// Package ratelimit provides token-bucket rate limiting for HTTP handlers.
//
// Use NewLimiter at process startup and share one Limiter across handlers.
// Limiters are safe for concurrent use.
package ratelimit
 
// Limiter controls request rate using a token bucket.
type Limiter struct { /* ... */ }
 
// Allow reports whether one event may proceed at time now.
// It is safe for concurrent use by multiple goroutines.
func (l *Limiter) Allow(now time.Time) bool { /* ... */ }

When to reach for this:

• Exporting new packages or public HTTP/gRPC APIs
• Onboarding engineers who ask "where is the docs?"
• Reviewing PRs that add exported types without comments
• Preparing a library for external or cross-team consumption

Working Example

A library adds executable documentation and a package overview.

// 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/ratelimit

What this demonstrates:

• Examples live in *_test.go with Example prefix and optional // Output:.
• go test runs examples as tests; broken examples fail CI.
• Package comment orients readers before they read Limiter methods.
• Reviewers block merge if exported symbols lack comments.

Deep Dive

How It Works

• The go/doc tool parses comments immediately above exported declarations.
• Package comments sit before package clause (only one file per package should carry the main block).
• Sentences should be complete phrases; godoc renders them as reference prose.
• pkg.go.dev shows examples, constants, and deprecated notices from comment text.

Comment Checklist

Go Notes

// Bad - comment does not start with symbol name
// Returns a limiter for rate control.
func NewLimiter(rate int, window time.Duration) *Limiter
 
// Good
// NewLimiter returns a Limiter that allows rate events per window.
func NewLimiter(rate int, window time.Duration) *Limiter

// ErrRateExceeded indicates the client exceeded quota.
// Callers may retry after RetryAfter duration.
var ErrRateExceeded = errors.New("rate exceeded")

Link related types with plain text names; godoc auto-links identifiers when possible.

Internal Playbooks vs godoc

• godoc: stable API contracts, usage, errors, concurrency.
• Playbooks (wiki/README): deploy steps, on-call, credentials, architecture diagrams.
• Onboarding docs: team-specific ramp (this section's pages).
• Do not paste secrets or environment-specific URLs into godoc comments.

Gotchas

• Comment on wrong line - godoc attaches to next exported symbol only. Fix: comment directly above declaration with no blank line.
• Package comment in every file - pkg.go.dev shows duplicates awkwardly. Fix: one doc.go or designated file per package.
• Examples with network I/O - flaky on pkg.go.dev. Fix: use fakes or httptest.Server with deterministic output.
• Documenting unexported helpers - noise for readers. Fix: comment only exports unless internal team package with clear audience.
• Stale comments after behavior change - worse than no comment. Fix: require doc updates in PR template for API changes.
• Using godoc for incident runbooks - operators need searchable wikis with paging links. Fix: cross-link playbook from README, not from symbol comments.

Alternatives

FAQs

Related

• Team Onboarding Basics - go doc exploration exercise
• Code Review Culture for Go - blocking on missing export docs
• Examples as Executable Documentation - Example test details
• Coding Standards & Doc Conventions - org-wide prose rules
• Effective Go Rules Checklist - godoc items in review

Stack versions: This page was written for Go 1.26.x (Green Tea GC default, go fix modernizers - verify patch at build), chi (latest - verify at build), gin (latest - verify at build), echo (latest - verify at build), google.golang.org/grpc (latest - verify at build), sigs.k8s.io/controller-runtime (latest - verify at build), kubebuilder (latest - verify at build), tinygo (latest - verify board targets at build), wazero (latest - verify at build), and golangci-lint (latest - verify linter set at build).