Writing comments

Instructions

•
Standalone comments MUST be full sentences, starting with a capital letter and ending with a period.
code
```
BAD
// Start dispatcher

GOOD
// Start the dispatcher.
```
•
Inline comments (appearing at the end of a line of code) SHOULD be fragments starting with a lowercase letter
code
```
BAD
eventChan chan *Event // Channel for events

GOOD
eventChan chan *Event // channel for events
```

•

If an inline comment has to become multi-line, it MUST be converted to a standalone comment, and become a full sentence.

code

BAD
eventChan chan *Event // channel for events
                      // received from the network

GOOD
// Channel for events received from the network.
eventChan chan *Event

•

Multi-line comments MUST use //, not /* ... */.

code

BAD
/*
 This is a multi-line comment.
 It uses block comment syntax.
*/

GOOD
// This is a multi-line comment.
// It uses line comment syntax.

•
Apply semantic line breaks formatting to long comments.
•
Avoid unnecessary comments that do not add value. See Avoid unnecessary comments below.

•

When available, explain the "why" behind non-obvious code, not just the "what".

code

BAD
// Start workers.
for i := 0; i < numWorkers; i++ {
    go worker()
}

GOOD
// Workers must be spawned before sending the first event
// or there will be a deadlock.
for i := 0; i < numWorkers; i++ {
    go worker()
}

Language-Specific Guidelines

Go

When writing comments for exported functions, types, or variables in Go, ALWAYS use the GoDoc style, starting with the name of the item being documented.

code

BAD
// This function starts the dispatcher.
func StartDispatcher() { ... }

GOOD
// StartDispatcher starts the dispatcher.
func StartDispatcher() { ... }

Avoid unnecessary comments

Do not add comments that do not add value. Consider:

•
Is the code self-explanatory? If yes, DELETE the comment.
•
Does the comment just restate what the code does? If yes, DELETE the comment.
•
Is the comment out of date or incorrect? If yes, UPDATE or DELETE the comment.

Examples of comments to DELETE:

code

// Close the channel
close(ch)

// Start the worker
go worker()

// Increment counter
count++

Examples of comments to KEEP:

code

// Workers must be spawned before sending the first event
// or there will be a deadlock.
for i := 0; i < numWorkers; i++ { go worker() }

// Use a nil channel to disable this select case when buffer is empty.
processChan = nil

The key insight is:

•Comments are NOT there to narrate the code.
•
Comments are there to:
- •provide additional context and explanation that is not obvious from the code itself
- •for large code blocks, allow readers to quickly grasp the intent without reading every line of code.