go-standards

Canonical Go Best Practices

These standards define "Canonical Go" style. They complement Effective Go and Google's Go style guidelines. All new code must abide by go fmt and go vet.

For full code examples of every rule, see examples.md.

---

Cosmetic Discipline

Braces

• No extra newlines between braces. Use compact struct/slice literal style:

tests := []struct{
    name string
}{{
    name: "foo",
}, {
    name: "bar",
}}

Spacing (blank lines)

Use blank lines semantically, not aesthetically. Rules:

• Declaration + immediate use/check = no blank line (strongly associated)
• Declaration used across multiple blocks = blank line after declaration
• Declaration + check (≤3 lines) = no blank line; check >3 lines = blank line after

// GOOD: declaration and check are strongly associated
x, err := foo()
if err != nil {
    return nil, err
}

Grouping

• Don't interleave unrelated code. Group strongly interdependent sections.
• Declare closures close to where they're used if they capture values.
• If no captures needed, define at top of highest scope to make that obvious.
• Consider whether a closure is needed at all — prefer simple top-to-bottom flow.

---

Naming Discipline

Names should:

• Say what they mean — copy(dest, source) not copy(x, y)
• Have consistent word order — if the API uses verbNoun, keep using verbNoun
• Be concise — shorter is better when unambiguous
• Use simple words — prefer short common words over long rare ones
• Be unified — one name per concept across the codebase
• Avoid including types — needle not needleString (unless disambiguating)
• Use US spelling (company policy)

If a good name can't be found, the API probably needs refactoring.

Take extreme care with exported names — they can't be changed without breaking consumers.

---

Error Discipline