22 lines
1.3 KiB
Markdown
22 lines
1.3 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.
|
|
|
|
Adapted from [Flow's Go documentation guide](https://github.com/onflow/flow-go/blob/master/docs/agents/GoDocs.md).
|