Skip to main content

Commenting Guidelines

These guidelines follow the official Go doc comment specification at https://go.dev/doc/comment.

Package Comments​

Begin with "Package <name>" followed by a description of what the package provides.

// Package model defines the message contracts exchanged between actors.
package model

For main packages, begin with the program name capitalized.

Functions and Methods​

Lead with a complete sentence naming the symbol. Focus on what the caller needs to know.

// Fetch retrieves the HTML at url and returns the number of lines
// inside the <body> element.
func (w *WorkerActor) fetch(url string) *model.FetchResult
  • For boolean returns, use "reports whether", not "returns true if" or "checks whether".
  • Name return values in the comment when explaining multiple returns.
  • Document special cases and edge cases.

Types​

Explain what each instance represents or provides. State concurrency safety when it differs from the default.

// OrchestratorActor holds the pending URL queue and supervises worker children.
// It is not safe for concurrent use; all access is serialised through the actor mailbox.
type OrchestratorActor struct { ... }

For structs with exported fields, document each field inline:

type LimitedReader struct {
    R Reader // underlying reader
    N int64  // max bytes remaining; Read returns EOF when N <= 0
}

Constants and Variables​

A single doc comment may introduce a grouped declaration block. Individual items take end-of-line comments.

// Routing strategies for the worker pool.
const (
    RoundRobin      = iota // distribute evenly across workers
    ConsistentHash         // same key always routes to the same worker
    Broadcast              // send to all workers
)

Formatting​

Paragraphs​

Consecutive unindented lines form a paragraph. Separate paragraphs with a blank comment line (//).

Headings​

// # Section Title

Must be preceded and followed by blank lines. Requires a space after #.

Reference exported identifiers and packages with [brackets]:

// dispatch sends a [model.FetchRequest] to the next idle worker.

Lists​

Bullet list (use -):

// Supervision responses:
//
//   - Resume: keep state, continue processing.
//   - Restart: discard state, create new instance.
//   - Stop: terminate permanently.

Code Blocks​

Indent with a single tab, preceded by a blank comment line:

// Example:
//
//  ctx.Send(msg.Worker, &model.FetchRequest{URL: url})

Common Mistakes​

WrongRight
// returns true if the worker is ready// reports whether the worker is ready
Comment separated from declaration by blank lineComment directly above declaration
Starting with a verb instead of the symbol nameLead with the symbol name