Go documentation and traceability review
Contract Documentation
Behavior changes need matching documentation. Review code comments, help text, README material, module docs, and public reference pages when the change alters user-visible behavior, CLI flags, API responses, validation rules, file formats, or architecture boundaries. Documentation can be concise, but it must not describe a shape the code no longer has.
When a change affects multiple surfaces, the review should name the stale or missing surface instead of asking for “docs” in general. A flag change, for example, may require help text, a README example, machine-readable command metadata, tests, and a public module page update.
Comments and Invariants
Comments should preserve intent and invariants. They should explain ownership,
safety constraints, non-obvious ordering, compatibility requirements, or why a
simpler-looking change would be wrong. Every top-level production-code unit
should have a short purpose comment, and non-obvious integration points should
keep concise Used by: notes accurate during refactors. Comments that restate
syntax should be removed or replaced with a better name.
Bad:
// Loop over users.
for _, user := range users {
process(user)
}
Better:
// Process users in stable ID order so audit output is reproducible.
sort.Slice(users, func(i, j int) bool { return users[i].ID < users[j].ID })
for _, user := range users {
process(user)
}
The better comment explains the invariant a future edit must preserve.