Files
beatglow/docs/agents/GoDocs.md
T

1.2 KiB

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.