z-go-documentation

Go Documentation

Writing Principles

Code shows what; comments explain why and when. Every doc comment must add information the reader cannot read directly from the signature.

Anti-patterns to remove on sight:

• Paraphrase comments that start with the name and stop there (// Foo returns a foo.)
• Signature restatement (// Parse parses the input string into T.)
• Marketing vocabulary (seamlessly, robust, enterprise-grade)
• Hedged future claims (easy to extend, for future use)

Package Comments

Every package needs one. Place it in doc.go for non-trivial packages:

// Package orders implements the order lifecycle — creation, fulfillment, and cancellation.
// It exposes domain types and use-case interfaces consumed by the transport layer.
package orders

One-line is fine for simple packages. Multi-line for packages with multiple responsibilities.

Exported Symbol Comments

Every exported function, method, type, and constant must have a doc comment.

Start with the symbol name + a verb phrase. Focus on when to call it, constraints, and error conditions — not what the code already shows:

// Create persists a new order and returns its assigned ID.
// Returns ErrDuplicate if an order with the same idempotency key already exists.
// Returns ErrInvalidItem if any line item has a zero quantity or unknown SKU.
func (r *OrderRepository) Create(ctx context.Context, o *Order) (string, error)

Deprecated symbols:

// Deprecated: Use CreateV2 which accepts a context and supports idempotency keys.
func Create(o *Order) (string, error)

For APIs that own resources or start concurrent work, document the applicable lifecycle contract:

• State who closes, cancels, or otherwise releases each resource, and when.
• State concurrent-use guarantees and any synchronization the caller must provide.
• Explain context lifetimes or cancellation behavior that differ from ordinary call-scoped use.
• State whether background work continues after return and how callers stop it and wait for completion.

Omit guarantees already implied by the API's conventional behavior.

Quick Reference

Example Test Functions

Nice-to-have, not a default — rarely used in practice. Write ExampleXxx in _test.go files when a runnable usage snippet earns its keep for a public API; they run under go test and appear on pkg.go.dev:

func ExampleOrderRepository_Create() {
    repo := orders.NewRepository(db)
    id, err := repo.Create(ctx, &orders.Order{
        CustomerID: "c-123",
        Items:      []orders.Item{{SKU: "A1", Qty: 2}},
    })
    if err != nil {
        log.Fatal(err)
    }
    fmt.Println(id != "")
    // Output:
    // true
}

Output comments are mandatory for the test runner to verify them. Omit only when output is non-deterministic (add // Unordered output: for set results).

README

Title, badges (Go version, license, CI, pkg.go.dev), 1-2 sentence summary, install + minimal working example, features, link to CONTRIBUTING, license. Order matters more than exhaustiveness — a reader should hit a working example before a feature list.

CONTRIBUTING

Get a contributor running tests and opening a PR in under 10 minutes: prerequisites, clone, build, test, PR process. If setup takes longer, fix the tooling first (Makefile, Taskfile, devcontainer).

CHANGELOG

Does not cover CHANGELOG maintenance; see [[z-changelog]].

Library vs Application Docs

Libraries: doc comments are the primary deliverable; Example tests are a nice-to-have on top, not required. Playground links in comments: // Play: https://go.dev/play/p/xxx.

Applications: --help is the primary doc surface. Document all env vars, config keys, and CLI flags. Installation section must cover binary, go install, and Docker.

API Documentation

Prefer codegen from schema over annotation-driven generation — schema is the source of truth.

llms.txt

Optional — zero adoption in practice so far. Add it only when a concrete agent-consumption need comes up, not by default. If added: a plain-text, structured overview at the repo root — project purpose, key packages, public API surface, and links to machine-readable specs (OpenAPI, proto files). Keep it factual — no marketing.

Do not

• Write comments that only restate what the signature shows.
• Use // TODO as a substitute for a real doc comment on an exported symbol.
• Skip the package comment on non-trivial packages.
• Put // Output: blocks in Example functions when output is truly non-deterministic

(use // Unordered output: for sets, or drop the output check and accept the example won't be verified).

• Commit llms.txt with speculative or future-tense claims.

Verify

Review changed API comments against the implementation. Verify cleanup ownership, concurrent-use guarantees, and exceptional context behavior wherever applicable. For background work, verify the documented stop and completion mechanism.

go list ./...                 # select the affected package
go doc -all ./path/to/package # render that package's exported API
timeout 5m go test -parallel 4 -p 2 -run Example -timeout 2m ./...    # verify all Example functions pass