Docs and comments

Canonical guidance

• Write package comments for packages users import directly.
• Start doc comments with the declared identifier name.
• Explain behavior, contracts, and caveats, not obvious syntax.
• Keep comments current or delete them.

Use when

• documenting exported APIs
• reviewing public package quality
• preparing a library for outside use

Avoid

• comments that merely paraphrase code
• stale comments that contradict behavior
• documenting only what, never why or when

Preferred pattern

// Fetch loads the user by ID and returns ErrNotFound when no row exists.
func Fetch(ctx context.Context, id string) (User, error)

Anti-pattern

// Fetch fetches the user.
func Fetch(ctx context.Context, id string) (User, error)

Explanation: This anti-pattern is tempting when documenting quickly, but comments that restate code add noise and go stale without helping callers.

Why

• in Go, documentation is tightly integrated with package browsing
• good comments lower API misuse and reduce source-diving