Files

20 lines
1.2 KiB
Markdown

# Go documentation
- Document new or changed exported APIs and interfaces. Explain private code when
its lifecycle, protocol behavior or invariants are not clear from the code.
- Start API comments with the declared name and write complete sentences. Use
paragraphs and Go doc links such as `[Player]` for relevant Go identifiers.
- Describe the contract: parameter constraints, units, defaults, return values,
blocking behavior and resource ownership when they matter to callers.
- For error returns, explain actionable failure conditions and recognizable
sentinel errors that the implementation actually returns. Do not invent error
types, guarantees or recovery behavior.
- State concurrency restrictions explicitly. Do not assume a type is safe for
concurrent use simply because no warning exists.
- Keep interface contracts and implementations consistent. Explain meaningful
deviations rather than copying comments mechanically.
- For documentation-only tasks, preserve runtime behavior. Correct inaccurate
documentation after checking the implementation; keep separate logic fixes scoped.
- Wrap prose around 100 characters where practical. Avoid documenting obvious
implementation steps or adding repetitive boilerplate.