
golang-skills
20 Go skills (each under 225 lines) with progressive disclosure, conditional cross-references, and bundled automation. Covers style, naming, error handling, testing, concurrency, generics, logging, documentation, performance, and more.
- version
- 1.8.0
- GitHub stars
- 195
Install
/plugin install golang-skills@golang-skillsRun it inside Claude Code after adding the marketplace with /plugin marketplace add cxuu/golang-skills.
Contents
Discovered from sourceSkills 20
Go Code Review Checklist
Compatibility:
references/WEB-SERVER.mduseslog/slogexamples that require Go 1.21+.
Resource Routing
assets/review-template.md- Use when formatting review output with Must Fix, Should Fix, and Nits sections.scripts/pre-review.sh- Run before manual review to collect gofmt, go vet, and golangci-lint results.references/WEB-SERVER.md- Read when reviewing an HTTP server that combines concurrency, context, logging, error handling, and shutdown behavior.
Review Procedure
Use
assets/review-template.mdwhen formatting the output of a code review to ensure consistent structure with Must Fix / Should Fix / Nits severity grouping.
- Run
gofmt -d .andgo vet ./...to catch mechanical issues first - Read the diff file-by-file; for each file, check the categories below in order
- Flag issues with specific line references and the rule name
- After reviewing all files, re-read flagged items to verify they're genuine issues
- Summarize findings grouped by severity (must-fix, should-fix, nit)
Validation: After completing the review, re-read the diff once more to verify every flagged issue is real. Remove any finding you cannot justify with a specific line reference.
Formatting
- gofmt: Code is formatted with
gofmtorgoimports→ go-linting
Documentation
- Comment sentences: Comments are full sentences starting with the name being described, ending with a period → go-documentation
- Doc comments: All exported names have doc comments; non-trivial unexported declarations too → go-documentation
- Package comments: Package comment appears adjacent to package clause with no blank line → go-documentation
- Named result parameters: Only used when they clarify meaning (e.g., multiple same-type returns), not just to enable naked returns → go-documentation
Error Handling
- Handle errors: No discarded errors with
_; handle, return, or (exceptionally) panic → go-error-handling - Error strings: Lowercase, no punctuation (unless starting with proper noun/acronym) → go-error-handling
- In-band errors: No magic values (-1, "", nil); use multiple returns with error or ok bool → go-error-handling
- Indent error flow: Handle errors first and return; keep normal path at minimal indentation → go-error-handling
Naming
- MixedCaps: Use
MixedCapsormixedCaps, never underscores; unexported ismaxLengthnotMAX_LENGTH→ go-naming - Initialisms: Keep consistent case:
URL/url,ID/id,HTTP/http(e.g.,ServeHTTP,xmlHTTPRequest) → go-naming - Variable names: Short names for limited scope (
i,r,c); longer names for wider scope → go-naming - Receiver names: One or two letter abbreviation of type (
cforClient); nothis,self,me; consistent across methods → go-naming - Package names: No stuttering (use
chubby.Filenotchubby.ChubbyFile); avoidutil,common,misc→ go-packages - Avoid built-in names: Don't shadow
error,string,len,cap,append,copy,new,make→ go-declarations
Concurrency
- Goroutine lifetimes: Clear when/whether goroutines exit; document if not obvious → go-concurrency
- Synchronous functions: Prefer sync over async; let callers add concurrency if needed → go-concurrency
- Contexts: First parameter; not in structs; no custom Context types; pass even if you think you don't need to → go-context
Interfaces
- Interface location: Define in consumer package, not implementor; return concrete types from producers → go-interfaces
- No premature interfaces: Don't define before used; don't define "for mocking" on implementor side → go-interfaces
- Receiver type: Use pointer if mutating, has sync fields, or is large; value for small immutable types; don't mix → go-interfaces
Data Structures
- Empty slices: Prefer
var t []string(nil) overt := []string{}(non-nil zero-length) → go-data-structures - Copying: Be careful copying structs with pointer/slice fields; don't copy
*Tmethods' receivers by value → go-data-structures
Security
- Crypto rand: Use
crypto/randfor keys, notmath/rand→ go-defensive - Don't panic: Use error returns for normal error handling; panic only for truly exceptional cases → go-defensive
Declarations and Initialization
- Group similar: Related
var/const/typein parenthesized blocks; separate unrelated → go-declarations - var vs :=: Use
varfor intentional zero values;:=for explicit assignments → go-declarations - Reduce scope: Move declarations close to usage; use if-init to limit variable scope → go-declarations
- Struct init: Always use field names; omit zero fields;
varfor zero structs → go-declarations - Use
any: Preferanyoverinterface{}in new code → go-declarations
Functions
- File ordering: Types → constructors → exported methods → unexported → utilities → go-functions
- Signature formatting: All args on own lines with trailing comma when wrapping → go-functions
- Naked parameters: Add
/* name */comments for ambiguous bool/int args, or use custom types → go-functions - Printf naming: Functions accepting format strings end in
fforgo vet→ go-functions
Style
- Line length: No rigid limit, but avoid uncomfortably long lines; break by semantics, not arbitrary length → go-style-core
- Naked returns: Only in short functions; explicit returns in medium/large functions → go-style-core
- Pass values: Don't use pointers just to save bytes; pass
stringnot*stringfor small fixed-size types → go-performance - String concatenation:
+for simple;fmt.Sprintffor formatting;strings.Builderfor loops → go-performance
Logging
- Use slog: New code uses
log/slog, notlogorfmt.Printlnfor operational logging → go-logging - Structured fields: Log messages use static strings with key-value attributes, not fmt.Sprintf → go-logging
- Appropriate levels: Debug for developer tracing, Info for notable events, Warn for recoverable issues, Error for failures → go-logging
- No secrets in logs: PII, credentials, and tokens are never logged → go-logging
Imports
- Import groups: Standard library first, then blank line, then external packages → go-packages
- Import renaming: Avoid unless collision; rename local/project-specific import on collision → go-packages
- Import blank:
import _ "pkg"only in main package or tests → go-packages - Import dot: Only for circular dependency workarounds in tests → go-packages
Generics
- When to use: Only when multiple types share identical logic and interfaces don't suffice → go-generics
- Type aliases: Use definitions for new types; aliases only for package migration → go-generics
Testing
- Examples: Include runnable
Examplefunctions or tests demonstrating usage → go-documentation - Useful test failures: Messages include what was wrong, inputs, got, and want; order is
got != want→ go-testing - TestMain: Use only when all tests need common setup with teardown; prefer scoped helpers first → go-testing
- Real transports: Prefer
httptest.NewServer+ real client over mocking HTTP → go-testing
Automated Checks
Run automated pre-review checks:
bash scripts/pre-review.sh ./... # text output
bash scripts/pre-review.sh --json ./... # structured JSON output
Or manually: gofmt -l <path> && go vet ./... && golangci-lint run ./...
Fix any issues before proceeding to the checklist above. For linter setup and configuration, see go-linting.
Related Skills
- Style foundations: See go-style-core when resolving formatting debates or applying the clarity > simplicity > concision priority
- Linting setup: See go-linting when configuring golangci-lint or adding automated checks to CI
- Error strategy: See go-error-handling when reviewing error wrapping, sentinel errors, or the handle-once pattern
- Naming conventions: See go-naming when evaluating identifier names, receiver names, or package-symbol stuttering
- Testing patterns: See go-testing when reviewing test code for table-driven structure, failure messages, or helper usage
- Concurrency safety: See go-concurrency when reviewing goroutine lifetimes, channel usage, or mutex placement
- Logging practices: See go-logging when reviewing log usage, structured logging, or slog configuration
Go Concurrency
Compatibility: Atomic examples may use standard-library typed atomics where available or
go.uber.org/atomicwhere a project already depends on it.
Resource Routing
references/GOROUTINE-PATTERNS.md- Read when starting, stopping, or waiting for goroutines.references/SYNC-PRIMITIVES.md- Read when choosing between mutexes, atomics, channels, and once-like primitives.references/BUFFER-POOLING.md- Read when considering channel-backed or sync.Pool-style reuse.references/ADVANCED-PATTERNS.md- Read for worker pools, pipelines, errgroup, and cancellation-heavy patterns.
Goroutine Lifetimes
Normative: When you spawn goroutines, make it clear when or whether they exit.
Goroutines can leak by blocking on channel sends/receives. The GC will not terminate a blocked goroutine even if no other goroutine holds a reference to the channel. Even non-leaking in-flight goroutines cause panics (send on closed channel), data races, memory issues, and resource leaks.
Core Rules
- Every goroutine needs a stop mechanism — a predictable end time, a cancellation signal, or both
- Code must be able to wait for the goroutine to finish
- No goroutines in
init()— expose lifecycle methods (Close,Stop,Shutdown) instead - Keep synchronization scoped — constrain to function scope, factor logic into synchronous functions
// Good: Clear lifetime with WaitGroup.Go (Go 1.25+)
var wg sync.WaitGroup
for item := range queue {
item := item
wg.Go(func() { process(ctx, item) })
}
wg.Wait()
// Bad: No way to stop or wait
go func() { for { flush(); time.Sleep(delay) } }()
Test for leaks with go.uber.org/goleak.
Principle: Never start a goroutine without knowing how it will stop.
Share by Communicating
"Do not communicate by sharing memory; instead, share memory by communicating."
This is Go's foundational concurrency design principle. Use channels for ownership transfer and orchestration — when one goroutine produces a value and another consumes it. Use mutexes when multiple goroutines access shared state and channels would add unnecessary complexity.
Default to channels. Fall back to sync.Mutex / sync.RWMutex when the
problem is naturally about protecting a shared data structure (e.g., a cache or
counter) rather than passing data between goroutines.
Synchronous Functions
Normative: Prefer synchronous functions over asynchronous ones.
| Benefit | Why |
|---|---|
| Localized goroutines | Lifetimes easier to reason about |
| Avoids leaks and races | Easier to prevent resource leaks and data races |
| Easier to test | Check input/output without polling |
| Caller flexibility | Caller adds concurrency when needed |
Advisory: It is quite difficult (sometimes impossible) to remove unnecessary concurrency at the caller side. Let the caller add concurrency when needed.
Zero-value Mutexes
The zero-value of sync.Mutex and sync.RWMutex is valid — almost never need
a pointer to a mutex.
// Good: Zero-value is valid // Bad: Unnecessary pointer
var mu sync.Mutex mu := new(sync.Mutex)
Don't embed mutexes — use a named mu field to keep Lock/Unlock as
implementation details, not exported API.
Channel Direction
Normative: Specify channel direction where possible.
Direction prevents errors (compiler catches closing a receive-only channel), conveys ownership, and is self-documenting.
func produce(out chan<- int) { /* send-only */ }
func consume(in <-chan int) { /* receive-only */ }
func transform(in <-chan int, out chan<- int) { /* both */ }
Channel Size: One or None
Channels should have size zero (unbuffered) or one. Any other size requires justification for:
- How the size was determined
- What prevents the channel from filling under load
- What happens when writers block
c := make(chan int) // unbuffered — Good
c := make(chan int, 1) // size one — Good
c := make(chan int, 64) // arbitrary — needs justification
Atomic Operations
Use atomic.Bool, atomic.Int64, etc. (stdlib sync/atomic since Go 1.19, or
go.uber.org/atomic) for type-safe
atomic operations. Raw int32/int64 fields make it easy to forget atomic
access on some code paths.
// Good: Type-safe // Bad: Easy to forget
var running atomic.Bool var running int32 // atomic
running.Store(true) atomic.StoreInt32(&running, 1)
running.Load() running == 1 // race!
Documenting Concurrency
Advisory: Document thread-safety when it's not obvious from the operation type.
Go users assume read-only operations are safe for concurrent use, and mutating operations are not. Document concurrency when:
- Read vs mutating is unclear — e.g., a
Lookupthat mutates LRU state - API provides synchronization — e.g., thread-safe clients
- Interface has concurrency requirements — document in type definition
Context Usage
For context.Context guidance (parameter placement, struct storage, custom types, derivation patterns), see the dedicated go-context skill.
Buffer Pooling with Channels
Use a buffered channel as a free list to reuse allocated buffers. This "leaky
buffer" pattern uses select with default for non-blocking operations.
Related Skills
- Context propagation: See go-context when passing cancellation, deadlines, or request-scoped values through goroutines
- Error handling: See go-error-handling when propagating errors from goroutines or using errgroup
- Defensive hardening: See go-defensive when protecting shared state at API boundaries or using defer for cleanup
- Interface design: See go-interfaces when choosing receiver types for types with sync primitives
External Resources
- Never start a goroutine without knowing how it will stop — Dave Cheney
- Rethinking Classical Concurrency Patterns — Bryan Mills (GopherCon 2018)
- When Go programs end — Go Time podcast
- go.uber.org/goleak — Goroutine leak detector for testing
- go.uber.org/atomic — Type-safe atomic operations
Go Context Usage
Compatibility:
contexthas been in the standard library since Go 1.7.
Resource Routing
references/PATTERNS.md- Read when deriving contexts, checking cancellation, handling HTTP request contexts, or using typed context-value keys.
Context as First Parameter
Functions that use a Context should accept it as their first parameter:
func F(ctx context.Context, /* other arguments */) error
func ProcessRequest(ctx context.Context, req *Request) (*Response, error)
This is a strong convention in Go that makes context flow visible and consistent across codebases.
Don't Store Context in Structs
Do not add a Context member to a struct type. Instead, pass ctx as a parameter
to each method that needs it:
// Bad: Context stored in struct
type Worker struct {
ctx context.Context // Don't do this
}
// Good: Context passed to methods
type Worker struct{ /* ... */ }
func (w *Worker) Process(ctx context.Context) error {
// Context explicitly passed — lifetime clear
}
Exception: Methods whose signature must match an interface in the standard library or a third-party library may need to work around this.
Don't Create Custom Context Types
Do not create custom Context types or use interfaces other than context.Context
in function signatures:
// Bad: Custom context type
type MyContext interface {
context.Context
GetUserID() string
}
// Good: Use standard context.Context with value extraction
func Process(ctx context.Context) error {
userID := GetUserID(ctx)
}
Where to Put Application Data
Consider these options in order of preference:
- Function parameters — most explicit and type-safe
- Receiver — for data that belongs to the type
- Globals — for truly global configuration (use sparingly)
- Context value — only for request-scoped data
Context values are appropriate for:
- Request IDs and trace IDs
- Authentication/authorization info that flows with requests
- Deadlines and cancellation signals
Context values are not appropriate for:
- Optional function parameters
- Data that could be passed explicitly
- Configuration that doesn't vary per-request
Common Patterns
Deriving Contexts
Always defer cancel() immediately after creating a derived context:
ctx, cancel := context.WithTimeout(ctx, 5*time.Second)
defer cancel()
Checking Cancellation
select {
case <-ctx.Done():
return ctx.Err()
default:
// Do work
}
Context Immutability
Contexts are immutable — it's safe to pass the same ctx to multiple
concurrent calls that share the same deadline and cancellation signal.
Related Skills
- Goroutine coordination: See go-concurrency when using context for goroutine cancellation, select-based timeouts, or errgroup
- Error handling: See go-error-handling when deciding how to wrap or return
ctx.Err()cancellation errors - Interface design: See go-interfaces when designing APIs that accept context alongside interfaces
- Request-scoped logging: See go-logging when injecting loggers into context or adding request IDs to structured log output
Go Control Flow
Resource Routing
references/SWITCH-PATTERNS.md- Read when using switch statements, type switches, fallthrough, or labeled breaks.references/BLANK-IDENTIFIER.md- Read when using_, blank imports, unused compile-time assertions, or intentional discards.
If with Initialization
if and switch accept an optional initialization statement. Use it to scope
variables to the conditional block:
if err := file.Chmod(0664); err != nil {
log.Print(err)
return err
}
If you need the variable beyond a few lines after the if, declare it
separately and use a standard if instead:
x, err := f()
if err != nil {
return err
}
// lots of code that uses x
Indent Error Flow (Guard Clauses)
When an if body ends with break, continue, goto, or return, omit the
unnecessary else. Keep the success path unindented:
f, err := os.Open(name)
if err != nil {
return err
}
d, err := f.Stat()
if err != nil {
f.Close()
return err
}
codeUsing(f, d)
Never bury normal flow inside an else when the if already returns.
Redeclaration and Reassignment
The := short declaration allows redeclaring variables in the same scope:
f, err := os.Open(name) // declares f and err
d, err := f.Stat() // declares d, reassigns err
A variable v may appear in a := declaration even if already declared,
provided:
- The declaration is in the same scope as the existing
v - The value is assignable to
v - At least one other variable is newly created by the declaration
Variable Shadowing
Warning: If v is declared in an outer scope, := creates a new
variable that shadows it — a common source of bugs:
// Bug: ctx inside the if block shadows the outer ctx
if *shortenDeadlines {
ctx, cancel := context.WithTimeout(ctx, 3*time.Second)
defer cancel()
}
// ctx here is still the original — the shadowed ctx didn't escape
// Fix: use = instead of :=
var cancel func()
ctx, cancel = context.WithTimeout(ctx, 3*time.Second)
For Loops
Go's for is its only looping construct, unifying while, do-while, and
C-style for:
// Condition-only (Go's "while")
for x > 0 {
x = process(x)
}
// Infinite loop
for {
if done() { break }
}
// C-style three-component
for i := 0; i < n; i++ { ... }
Range
range iterates over slices, maps, strings, and channels:
for i, v := range slice { ... } // index + value
for k, v := range myMap { ... } // key + value (non-deterministic order)
for i, r := range "héllo" { ... } // byte index + rune (not byte)
for v := range ch { ... } // receives until channel closed
Key rules:
- Range over strings yields runes, not bytes —
iis the byte offset - Range over maps has non-deterministic order — don't rely on it
- Use
_to discard the index or value:for _, v := range slice
Parallel Assignment
Go has no comma operator. Use parallel assignment for multiple loop variables:
for i, j := 0, len(a)-1; i < j; i, j = i+1, j-1 {
a[i], a[j] = a[j], a[i]
}
++ and -- are statements, not expressions — they cannot appear in parallel
assignment.
Switch: Labeled Break
break inside a switch within a for loop only breaks the switch.
Use a labeled break to exit the enclosing loop:
Loop:
for _, v := range items {
switch v.Type {
case "done":
break Loop // breaks the for loop
}
}
For type switches, see go-interfaces: Type Switch.
The Blank Identifier
Never discard errors carelessly — a nil dereference panic may follow.
Route compile-time interface assertions to go-interfaces.
Quick Reference
| Pattern | Go Idiom |
|---|---|
| If initialization | if err := f(); err != nil { } |
| Early return | Omit else when if body returns |
| Redeclaration | := reassigns if same scope + new var |
| Shadowing trap | := in inner scope creates new variable |
| Parallel assignment | i, j = i+1, j-1 |
| Expression-less switch | switch { case cond: } |
| Comma cases | case 'a', 'b', 'c': |
| No fallthrough | Default behavior (explicit fallthrough if needed) |
| Break from loop in switch | break Label |
| Discard value | _, err := f() |
| Side-effect import | import _ "pkg" |
| Interface check | Route to go-interfaces |
Related Skills
- Error flow: See go-error-handling when structuring guard clauses, early returns, or error-first patterns
- Type switches: See go-interfaces when using type switches, the comma-ok idiom, or interface satisfaction checks
- Nesting reduction: See go-style-core when reducing nesting depth or resolving formatting questions
- Variable scoping: See go-declarations when using if-init,
:=redeclaration, or reducing variable scope
Go Data Structures
Resource Routing
references/SLICES.md- Read when deciding nil versus empty slices, copying slices, or managing slice capacity and aliasing.
Choosing a Data Structure
What do you need?
├─ Ordered collection of items
│ ├─ Fixed size known at compile time → Array [N]T
│ └─ Dynamic size → Slice []T
│ ├─ Know approximate size? → make([]T, 0, capacity)
│ └─ Unknown size or nil-safe for JSON? → var s []T (nil)
├─ Key-value lookup
│ └─ Map map[K]V
│ ├─ Know approximate size? → make(map[K]V, capacity)
│ └─ Need a set? → map[T]struct{} (zero-size values)
└─ Need to pass to a function?
└─ Copy at the boundary if the caller might mutate it
When this skill does NOT apply: For concurrent access to data structures (mutexes, atomic operations), see go-concurrency. For defensive copying at API boundaries, see go-defensive. For pre-sizing capacity for performance, see go-performance.
Slices
The append Function
Always assign the result — the underlying array may change:
x := []int{1, 2, 3}
x = append(x, 4, 5, 6)
// Append a slice to a slice
x = append(x, y...) // Note the ...
Two-Dimensional Slices
Independent inner slices (can grow/shrink independently):
picture := make([][]uint8, YSize)
for i := range picture {
picture[i] = make([]uint8, XSize)
}
Single allocation (more efficient for fixed sizes):
picture := make([][]uint8, YSize)
pixels := make([]uint8, XSize*YSize)
for i := range picture {
picture[i], pixels = pixels[:XSize], pixels[XSize:]
}
Declaring Empty Slices
Prefer nil slices over empty literals:
// Good: nil slice
var t []string
// Avoid: non-nil but zero-length
t := []string{}
Both have len and cap of zero, but the nil slice is the preferred style.
Exception for JSON: A nil slice encodes to null, while []string{}
encodes to []. Use non-nil when you need a JSON array.
When designing interfaces, avoid distinguishing between nil and non-nil zero-length slices.
Maps
Implementing a Set
Use map[T]struct{} when the map is only a set. The empty struct takes no
storage and makes membership intent explicit:
attended := map[string]struct{}{"Ann": {}, "Joe": {}}
if _, ok := attended[person]; ok {
fmt.Println(person, "was at the meeting")
}
Use boolean map values only when the value carries a separate meaning beyond presence.
Copying
Be careful when copying a struct from another package. If the type has methods
on its pointer type (*T), copying the value can cause aliasing bugs.
General rule: Do not copy a value of type T if its methods are associated
with the pointer type *T. This applies to bytes.Buffer, sync.Mutex,
sync.WaitGroup, and types containing them.
// Bad: copying a mutex
var mu sync.Mutex
mu2 := mu // almost always a bug
// Good: pass by pointer
func increment(sc *SafeCounter) {
sc.mu.Lock()
sc.count++
sc.mu.Unlock()
}
Quick Reference
| Topic | Key Point |
|---|---|
| Slices | Always assign append result; nil slice preferred over []T{} |
| Sets | map[T]struct{} for membership-only sets |
| Copying | Don't copy T if methods are on *T; beware aliasing |
Related Skills
- Defensive copying: See go-defensive when copying slices or maps at API boundaries to prevent mutation
- Capacity hints: See go-performance when pre-sizing slices or maps for known workloads
- Iteration patterns: See go-control-flow when using range loops over slices, maps, or channels
- Declaration style: See go-declarations when choosing between
new,make,var, and composite literals
Go Declarations and Initialization
Compatibility: Examples may use
any, which requires Go 1.18+.
Resource Routing
references/SCOPE.md- Read when deciding betweenvar,:=, if-init, and narrow variable scope.references/IOTA.md- Read when designing constants or enum-like values.references/INITIALIZATION.md- Read when initializing structs, maps, zero values, or pointers.references/LITERALS.md- Read for composite literal formatting and keyed-field tradeoffs.references/STRUCTS.md- Read when designing or initializing structs.references/SHADOWING.md- Read when a declaration may shadow a builtin or outer variable.
Quick Reference: var vs :=
| Context | Use | Example |
|---|---|---|
| Top-level | var (always) | var _s = F() |
| Local with value | := | s := "foo" |
| Local zero-value (intentional) | var | var filtered []int |
| Type differs from expression | var with type | var _e error = F() |
Group Similar Declarations
Group related var, const, type in parenthesized blocks. Separate
unrelated declarations into distinct blocks.
// Bad
const a = 1
const b = 2
// Good
const (
a = 1
b = 2
)
Inside functions, group adjacent vars even if unrelated:
var (
caller = c.name
format = "json"
timeout = 5 * time.Second
)
Constants and iota
Start enums at one so the zero value represents invalid/unset:
const (
Add Operation = iota + 1
Subtract
Multiply
)
Use zero when the default behavior is desirable (e.g., LogToStdout).
Variable Scope
Use if-init to limit scope when the result is only needed for the error check:
if err := os.WriteFile(name, data, 0644); err != nil {
return err
}
Don't reduce scope if it forces deeper nesting or you need the result outside
the if. Move constants into functions when only used there.
Initializing Structs
- Always use field names (enforced by
go vet). Exception: test tables with ≤3 fields. - Omit zero-value fields — let Go set defaults.
- Use
varfor zero-value structs:var user Usernotuser := User{} - Use
&T{}overnew(T):sptr := &T{Name: "bar"}
Composite Literal Formatting
Use field names for external package types. Match closing brace indentation
with the opening line. Omit repeated type names in slice/map literals
(gofmt -s).
Initializing Maps
| Scenario | Use | Example |
|---|---|---|
| Empty, populated later | make(map[K]V) | m := make(map[string]int) |
| Nil declaration | var | var m map[string]int |
| Fixed entries at init | Literal | m := map[string]int{"a": 1} |
make() visually distinguishes empty-but-initialized from nil. Use size hints
when the count is known.
Raw String Literals
Use backtick strings to avoid hand-escaped characters:
// Bad
wantError := "unknown name:\"test\""
// Good
wantError := `unknown name:"test"`
Ideal for regex, SQL, JSON, and multi-line text.
Prefer any Over interface{}
Go 1.18+: use any instead of interface{} in all new code.
Avoid Shadowing Built-In Names
Never use predeclared identifiers (error, string, len, cap, append,
copy, new, make, close, delete, panic, recover, any, true,
false, nil, iota) as names. Use go vet to detect.
// Bad — shadows the builtin
var error string
// Good
var errorMessage string
Related Skills
- Naming conventions: See go-naming when choosing variable names, constant names, or deciding name length by scope
- Data structures: See go-data-structures when choosing between
newandmake, or initializing slices and maps - Control flow scoping: See go-control-flow when using if-init,
:=redeclaration, or avoiding variable shadowing - Capacity hints: See go-performance when pre-allocating maps or slices with known sizes
Go Defensive Programming Patterns
Compatibility: Crypto examples may use
crypto/rand.Text, which requires Go 1.24+.
Resource Routing
references/BOUNDARY-COPYING.md- Read when copying slices/maps across API boundaries.references/GLOBAL-STATE.md- Read when introducing or removing package globals.references/MUST-FUNCTIONS.md- Read when deciding whether a panic-on-error helper is acceptable.references/PANIC-RECOVER.md- Read when evaluating panic, recover, or crash containment.references/TIME-ENUMS-TAGS.md- Read when handling time types, enum zero values, or struct tags.
Defensive Checklist Priority
When hardening code at API boundaries, check in this order:
Reviewing an API boundary?
├─ 1. Error handling → Return errors; don't panic (see go-error-handling)
├─ 2. Input validation → Copy slices/maps received from callers
├─ 3. Output safety → Copy slices/maps before returning to callers
├─ 4. Resource cleanup → Use defer for Close/Unlock/Cancel
├─ 5. Interface checks → Route compile-time assertions to go-interfaces
├─ 6. Time correctness → Use time.Time and time.Duration, not int/float
├─ 7. Enum safety → Start iota at 1 so zero-value is invalid
└─ 8. Crypto safety → crypto/rand for keys, never math/rand
Quick Reference
| Pattern | Rule | Details |
|---|---|---|
| Boundary copies | Copy slices/maps on receive and return | BOUNDARY-COPYING.md |
| Defer cleanup | defer f.Close() right after os.Open | Below |
| Interface check | Compile-time satisfaction assertion | See go-interfaces |
| Time types | time.Time / time.Duration, never raw int | TIME-ENUMS-TAGS.md |
| Enum start | iota + 1 so zero = invalid | Below |
| Crypto rand | crypto/rand for keys, never math/rand | Below |
| Must functions | Only at init; panic on failure | MUST-FUNCTIONS.md |
| Panic/recover | Never expose panics across packages | PANIC-RECOVER.md |
| Mutable globals | Replace with dependency injection | Below |
Verify Interface Compliance
Route compile-time interface assertions to go-interfaces. Use this skill only to notice API-boundary robustness risk; the interface skill owns when an assertion is appropriate and the exact assertion shape.
Copy Slices and Maps at Boundaries
Slices and maps contain pointers to underlying data. Copy at API boundaries to prevent unintended modifications.
// Receiving: copy incoming slice
d.trips = make([]Trip, len(trips))
copy(d.trips, trips)
// Returning: copy map before returning
result := make(map[string]int, len(s.counters))
for k, v := range s.counters { result[k] = v }
Defer to Clean Up
Use defer to clean up resources (files, locks). Avoids missed cleanup on multiple return paths.
p.Lock()
defer p.Unlock()
if p.count < 10 {
return p.count
}
p.count++
return p.count
Defer overhead is negligible. Place defer f.Close() immediately after
os.Open for clarity. Arguments to deferred functions are evaluated when
defer executes, not when the function runs. Multiple defers execute in
LIFO order.
Struct Field Tags
Advisory: Always add explicit field tags to structs that are marshaled or unmarshaled.
type User struct {
Name string `json:"name" yaml:"name"`
Email string `json:"email" yaml:"email"`
}
Field tags are a serialization contract — renaming a struct field without updating the tag silently breaks wire compatibility. Treat tags as part of the public API for any type that crosses a serialization boundary.
Start Enums at One
Start enums at non-zero to distinguish uninitialized from valid values.
const (
Add Operation = iota + 1 // Add=1, zero value = uninitialized
Subtract
Multiply
)
Exception: When zero is the sensible default (e.g., LogToStdout = iota).
Time, Struct Tags, and Embedding
Avoid Mutable Globals
Inject dependencies instead of mutating package-level variables. This makes code testable without global save/restore.
type signer struct {
now func() time.Time // injected; tests replace with fixed time
}
func newSigner() *signer {
return &signer{now: time.Now}
}
Crypto Rand
Do not use math/rand or math/rand/v2 to generate keys — this is a
security concern. Time-seeded generators have predictable output.
import "crypto/rand"
func Key() string { return rand.Text() }
For text output, use crypto/rand.Text directly, or encode random bytes
with encoding/hex or encoding/base64.
Panic and Recover
Use panic only for truly unrecoverable situations. Library functions
should avoid panic.
func safelyDo(work *Work) {
defer func() {
if err := recover(); err != nil {
log.Println("work failed:", err)
}
}()
do(work)
}
Key rules:
- Never expose panics across package boundaries — always convert to errors
- Acceptable to panic in
init()if a library truly cannot set itself up - Use recover to isolate panics in server goroutine handlers
Must Functions
Must functions panic on error — use them only during program
initialization where failure means the program cannot run.
var validID = regexp.MustCompile(`^[a-z][a-z0-9-]{0,62}$`)
var tmpl = template.Must(template.ParseFiles("index.html"))
Related Skills
- Error handling: See go-error-handling when choosing between returning errors and panicking, or wrapping errors at boundaries
- Concurrency safety: See go-concurrency when protecting shared state with mutexes, atomics, or channels
- Interface checks: See go-interfaces when adding compile-time interface satisfaction checks
- Data structure copying: See go-data-structures when working with slice/map internals or pointer aliasing
Go Documentation
Resource Routing
scripts/check-docs.sh- Run when checking exported functions, types, methods, constants, and packages for missing doc comments.scripts/check-docs-ast.go- Implementation helper invoked bycheck-docs.sh; patch this when changing documentation analysis behavior.assets/doc-template.go- Use when starting a documented package or exported API.references/CONVENTIONS.md- Read when documenting parameters, context behavior, concurrency safety, cleanup, errors, or named results.references/EXAMPLES.md- Read when adding runnable examples or package examples.references/FORMATTING.md- Read when formatting Godoc lists, paragraphs, links, and code blocks.
Doc Comments
Normative: All top-level exported names must have doc comments.
Basic Rules
- Begin with the name of the object being described
- An article ("a", "an", "the") may precede the name
- Use full sentences (capitalized, punctuated)
// A Request represents a request to run a command.
type Request struct { ...
// Encode writes the JSON encoding of req to w.
func Encode(w io.Writer, req *Request) { ...
Unexported types/functions with unobvious behavior should also have doc comments.
Validation: After adding doc comments, run
bash scripts/check-docs.shto verify no exported symbols are missing documentation. Fix any gaps before proceeding.
Comment Sentences
Normative: Documentation comments must be complete sentences.
- Capitalize the first word, end with punctuation
- Exception: may begin with uncapitalized identifier if clear
- End-of-line comments for struct fields can be phrases
Comment Line Length
Advisory: Aim for ~80 columns, but no hard limit.
Break based on punctuation. Don't split long URLs.
Struct Documentation
Group fields with section comments. Mark optional fields with defaults:
type Options struct {
// General setup:
Name string
Group *FooGroup
// Customization:
LargeGroupThreshold int // optional; default: 10
}
Package Comments
Normative: Every package must have exactly one package comment.
// Package math provides basic constants and mathematical functions.
package math
- For
mainpackages, use the binary name:// The seed_generator command ... - For long package comments, use a
doc.gofile
What to Document
Advisory: Document non-obvious behavior, not obvious behavior.
| Topic | Document when... | Skip when... |
|---|---|---|
| Parameters | Non-obvious behavior, edge cases | Restates the type signature |
| Contexts | Behavior differs from standard cancellation | Standard ctx.Err() return |
| Concurrency | Ambiguous thread safety (e.g., read that mutates) | Read-only is safe, mutation is unsafe |
| Cleanup | Always document resource release | — |
| Errors | Sentinel values, error types (use *PathError) | — |
| Named results | Multiple params of same type, action-oriented names | Type alone is clear enough |
Key principles:
- Context cancellation returning
ctx.Err()is implied — don't restate it - Read-only ops are assumed thread-safe; mutations assumed unsafe — don't restate
- Always document cleanup requirements (e.g.,
Call Stop to release resources) - Use pointer in error type docs (
*PathError) for correcterrors.Is/errors.As - Don't name results just to enable naked returns — clarity > brevity
Runnable Examples
Advisory: Provide runnable examples in test files (
*_test.go).
func ExampleConfig_WriteTo() {
cfg := &Config{Name: "example"}
cfg.WriteTo(os.Stdout)
// Output:
// {"name": "example"}
}
Examples appear in Godoc attached to the documented element.
Quick Reference
| Topic | Key Rule |
|---|---|
| Doc comments | Start with name, use full sentences |
| Line length | ~80 chars, prioritize readability |
| Package comments | One per package, above package clause |
| Parameters | Document non-obvious behavior only |
| Contexts | Document exceptions to implied behavior |
| Concurrency | Document ambiguous thread safety |
| Cleanup | Always document resource release |
| Errors | Document sentinels and types (note pointer) |
| Examples | Use runnable examples in test files |
| Formatting | Blank lines for paragraphs, indent for code |
Related Skills
- Naming conventions: See go-naming when choosing names for the identifiers your doc comments describe
- Testing examples: See go-testing when writing runnable
Exampletest functions that appear in godoc - Linting enforcement: See go-linting when using revive or other linters to enforce doc comment presence
- Style principles: See go-style-core when balancing documentation verbosity against clarity and concision
Go Error Handling
Compatibility:
errors.Is,errors.As, and%wwrapping require Go 1.13+; structured logging examples may uselog/slogfrom Go 1.21+.
Resource Routing
scripts/check-errors.sh- Run when checking string-based error matching, bare error propagation, and log-and-return patterns.scripts/check-errors-ast.go- Implementation helper invoked bycheck-errors.sh; patch this when changing error-flow analysis behavior.references/ERROR-FLOW.md- Read when deciding where to handle, wrap, log, or return errors.references/ERROR-TYPES.md- Read when choosing sentinel errors, typed errors, or opaque errors.references/WRAPPING.md- Read when choosing%wversus%vor crossing package boundaries.
In Go, errors are values — they are created by code and consumed by code.
Choosing an Error Strategy
- System boundary (RPC, IPC, storage)? → Wrap with
%vto avoid leaking internals - Caller needs to match specific conditions? → Sentinel or typed error, wrap with
%w - Caller just needs debugging context? →
fmt.Errorf("...: %w", err) - Leaf function, no wrapping needed? → Return the error directly
Default: wrap with %w and place it at the end of the format string.
Core Rules
Never Return Concrete Error Types
Never return concrete error types from exported functions — a concrete nil
pointer can become a non-nil interface:
// Bad: Concrete type can cause subtle bugs
func Bad() *os.PathError { /*...*/ }
// Good: Always return the error interface
func Good() error { /*...*/ }
Error Strings
Error strings should not be capitalized and should not end with punctuation. Exception: exported names, proper nouns, or acronyms.
// Bad
err := fmt.Errorf("Something bad happened.")
// Good
err := fmt.Errorf("something bad happened")
For displayed messages (logs, test failures, API responses), capitalization is appropriate.
Return Values on Error
When a function returns an error, callers must treat all non-error return values as unspecified unless explicitly documented.
Tip: Functions taking a context.Context should usually return an error
so callers can determine if the context was cancelled.
Handling Errors
When encountering an error, make a deliberate choice — do not discard
with _:
- Handle immediately — address the error and continue
- Return to caller — optionally wrapped with context
- In exceptional cases —
log.Fatalorpanic
To intentionally ignore: add a comment explaining why.
n, _ := b.Write(p) // never returns a non-nil error
For related concurrent operations, use
errgroup:
g, ctx := errgroup.WithContext(ctx)
g.Go(func() error { return task1(ctx) })
g.Go(func() error { return task2(ctx) })
if err := g.Wait(); err != nil { return err }
Avoid In-Band Errors
Don't return -1, nil, or empty string to signal errors. Use multiple
returns:
// Bad: In-band error value
func Lookup(key string) int // returns -1 for missing
// Good: Explicit error or ok value
func Lookup(key string) (string, bool)
This prevents callers from writing Parse(Lookup(key)) — it causes a
compile-time error since Lookup(key) has 2 outputs.
Error Flow
Handle errors before normal code. Early returns keep the happy path unindented:
// Good: Error first, normal code unindented
if err != nil {
return err
}
// normal code
Handle errors once — either log or return, never both:
Error encountered?
├─ Caller can act on it? → Return (with context via %w)
├─ Top of call chain? → Log and handle
└─ Neither? → Log at appropriate level, continue
Error Types
Advisory: Recommended best practice.
| Caller needs to match? | Message type | Use |
|---|---|---|
| No | static | errors.New("message") |
| No | dynamic | fmt.Errorf("msg: %v", val) |
| Yes | static | var ErrFoo = errors.New("...") |
| Yes | dynamic | custom error type |
Default: Wrap with fmt.Errorf("...: %w", err). Escalate to sentinels for
errors.Is(), to custom types for errors.As().
Error Wrapping
Advisory: Recommended best practice.
- Use
%v: At system boundaries, for logging, to hide internal details - Use
%w: To preserve error chain forerrors.Is/errors.As
Key rules: Place %w at the end. Add context callers don't have. If
annotation adds nothing, return err directly.
Validation: After implementing error handling, run
bash scripts/check-errors.shto detect common anti-patterns. Then rungo vet ./...to catch additional issues.
Related Skills
- Error naming: See go-naming when naming sentinel errors (
ErrFoo) or custom error types - Testing errors: See go-testing when testing error semantics with
errors.Is/errors.Asor writing error-checking helpers - Panic handling: See go-defensive when deciding between panic and error returns, or writing recover guards
- Guard clauses: See go-control-flow when structuring early-return error flow or reducing nesting
- Logging decisions: See go-logging when choosing log levels, configuring structured logging, or deciding what context to include in log messages
Functional Options Pattern
Functional options is a pattern where you declare an opaque Option type that records information in an internal struct. The constructor accepts a variadic number of these options and applies them to configure the result.
Resource Routing
references/OPTIONS-VS-STRUCTS.md- Read when choosing between config structs and functional options, implementing the full interface-based option pattern, or evaluating hybrid constructor APIs.
When to Use
Use functional options when:
- 3+ optional arguments on constructors or public APIs
- Extensible APIs that may gain new options over time
- Clean caller experience is important (no need to pass defaults)
The Pattern
Core Components
- Unexported
optionsstruct - holds all configuration - Exported
Optioninterface - with unexportedapplymethod - Option types - implement the interface
With*constructors - create options
Option Interface
type Option interface {
apply(*options)
}
The unexported apply method ensures only options from this package can be used.
Comparison: Functional Options vs Config Struct
| Aspect | Functional Options | Config Struct |
|---|---|---|
| Extensibility | Add new With* functions | Add new fields (may break) |
| Defaults | Built into constructor | Zero values or separate defaults |
| Caller experience | Only specify what differs | Must construct entire struct |
| Testability | Options are comparable | Struct comparison |
| Complexity | More boilerplate | Simpler setup |
Prefer Config Struct when: Fewer than 3 options, options rarely change, all options usually specified together, or internal APIs only.
Why Not Closures?
The interface approach is preferred over closure-only options because:
- Testability - Options can be compared in tests and mocks
- Debuggability - Options can implement
fmt.Stringer - Flexibility - Options can implement additional interfaces
- Visibility - Option types are visible in documentation
Quick Reference
// 1. Unexported options struct with defaults
type options struct {
field1 Type1
field2 Type2
}
// 2. Exported Option interface, unexported method
type Option interface {
apply(*options)
}
// 3. Option type + apply + With* constructor
type field1Option Type1
func (o field1Option) apply(opts *options) { opts.field1 = Type1(o) }
func WithField1(v Type1) Option { return field1Option(v) }
// 4. Constructor applies options over defaults
func New(required string, opts ...Option) (*Thing, error) {
o := options{field1: defaultField1, field2: defaultField2}
for _, opt := range opts {
opt.apply(&o)
}
// ...
}
Checklist
-
optionsstruct is unexported -
Optioninterface has unexportedapplymethod - Each option has a
With*constructor - Defaults are set before applying options
- Required parameters are separate from
...Option
Related Skills
- Interface design: See go-interfaces when designing the
Optioninterface or choosing between interface and closure approaches - Naming conventions: See go-naming when naming
With*constructors, option types, or the unexported options struct - Function design: See go-functions when organizing constructors within a file or formatting variadic signatures
- Documentation: See go-documentation when documenting
Optiontypes,With*functions, or constructor behavior
External Resources
- Self-referential functions and the design of options - Rob Pike
- Functional options for friendly APIs - Dave Cheney
Go Function Design
Resource Routing
references/SIGNATURES.md- Read when designing parameters, return values, named results, or signature readability.references/PRINTF-STRINGER.md- Read when using fmt verbs, Stringer, GoStringer, Formatter, or Printf-style function naming.
When this skill does NOT apply: For functional options constructors (
WithTimeout,WithLogger), see go-functional-options. For error return conventions, see go-error-handling. For naming functions and methods, see go-naming.
Function Grouping and Ordering
Organize functions in a file by these rules:
- Functions sorted in rough call order
- Functions grouped by receiver
- Exported functions appear first, after
struct/const/vardefinitions NewXxx/newXxxconstructors appear right after the type definition- Plain utility functions appear toward the end of the file
type something struct{ ... }
func newSomething() *something { return &something{} }
func (s *something) Cost() int { return calcCost(s.weights) }
func (s *something) Stop() { ... }
func calcCost(n []int) int { ... }
Function Signatures
Keep the signature on a single line when possible. When it must wrap, put all arguments on their own lines with a trailing comma:
func (r *SomeType) SomeLongFunctionName(
foo1, foo2, foo3 string,
foo4, foo5, foo6 int,
) {
foo7 := bar(foo1)
}
Add /* name */ comments for ambiguous arguments, or better yet, replace naked
bool parameters with custom types.
Pointers to Interfaces
You almost never need a pointer to an interface. Pass interfaces as values — the underlying data can still be a pointer.
// Bad: pointer to interface
func process(r *io.Reader) { ... }
// Good: pass the interface value
func process(r io.Reader) { ... }
Printf and Stringer
Printf-style Function Names
Functions that accept a format string should end in f for go vet support.
Declare format strings as const when used outside Printf calls.
Prefer %q over %s with manual quoting when formatting strings for logging
or error messages — it safely escapes special characters and wraps in quotes:
return fmt.Errorf("unknown key %q", key) // produces: unknown key "foo\nbar"
See go-functional-options when designing a constructor with 3+ optional parameters.
Quick Reference
| Topic | Rule |
|---|---|
| File ordering | Type -> constructor -> exported -> unexported -> utils |
| Signature wrapping | All args on own lines with trailing comma |
| Naked parameters | Add /* name */ comments or use custom types |
| Pointers to interfaces | Almost never needed; pass interfaces by value |
| Printf function names | End with f for go vet support |
Related Skills
- Error returns: See go-error-handling when designing error return patterns or wrapping errors in multi-return functions
- Naming conventions: See go-naming when naming functions, methods, or choosing getter/setter patterns
- Functional options: See go-functional-options when designing a constructor with 3+ optional parameters
- Formatting principles: See go-style-core when deciding line length, naked returns, or signature formatting
Go Generics and Type Parameters
Compatibility: Generics require Go 1.18+.
Resource Routing
references/CONSTRAINTS.md- Read when composing constraints, using type sets, or choosing between generics and interfaces.
When to Use Generics
Start with concrete types. Generalize only when a second type appears.
Prefer Generics When
- Multiple types share identical logic (sorting, filtering, map/reduce)
- You would otherwise rely on
anyand excessive type switching - You are building a reusable data structure (concurrent-safe set, ordered map)
Avoid Generics When
- Only one type is being instantiated in practice
- Interfaces already model the shared behavior cleanly
- The generic code is harder to read than the type-specific alternative
"Write code, don't design types." — Robert Griesemer and Ian Lance Taylor
Decision Flow
Do multiple types share identical logic?
├─ No → Use concrete types
├─ Yes → Do they share a useful interface?
│ ├─ Yes → Use an interface
│ └─ No → Use generics
Bad:
// Premature generics: only ever called with int
func Sum[T constraints.Integer | constraints.Float](vals []T) T {
var total T
for _, v := range vals {
total += v
}
return total
}
Good:
func SumInts(vals []int) int {
var total int
for _, v := range vals {
total += v
}
return total
}
Type Parameter Naming
| Name | Typical Use |
|---|---|
T | General type parameter |
K | Map key type |
V | Map value type |
E | Element/item type |
For complex constraints, a short descriptive name is acceptable:
func Marshal[Opts encoding.MarshalOptions](v any, opts Opts) ([]byte, error)
Type Aliases vs Type Definitions
Type aliases (type Old = new.Name) are rare — use only for package migration
or gradual API refactoring.
Constraint Composition
Combine constraints with ~ (underlying type) and | (union):
type Numeric interface {
~int | ~int8 | ~int16 | ~int32 | ~int64 |
~float32 | ~float64
}
func Sum[T Numeric](vals []T) T {
var total T
for _, v := range vals {
total += v
}
return total
}
Use the constraints package or cmp package (Go 1.21+) for standard constraints
like cmp.Ordered instead of writing your own.
Common Pitfalls
Don't Wrap Standard Library Types
// Bad: generic wrapper adds complexity without value
type Set[T comparable] struct {
m map[T]struct{}
}
// Better: use map[T]struct{} directly when the usage is simple
seen := map[string]struct{}{}
Generics justify their complexity when they eliminate duplication across multiple call sites. A single-use generic is just indirection.
Don't Use Generics for Interface Satisfaction
// Bad: T is only used to satisfy an interface — just use the interface
func Process[T io.Reader](r T) error { ... }
// Good: accept the interface directly
func Process(r io.Reader) error { ... }
Avoid Over-Constraining
// Bad: constraint is more restrictive than needed
func Contains[T interface{ ~int | ~string }](slice []T, target T) bool { ... }
// Good: comparable is sufficient
func Contains[T comparable](slice []T, target T) bool { ... }
Quick Reference
| Topic | Guidance |
|---|---|
| When to use generics | Only when multiple types share identical logic and interfaces don't suffice |
| Starting point | Write concrete code first; generalize later |
| Naming | Single uppercase letter (T, K, V, E) |
| Type aliases | Same type, alternate name; use only for migration |
| Constraint composition | Use ~ for underlying types, ` |
| Common pitfall | Don't genericize single-use code or when interfaces suffice |
Related Skills
- Interfaces vs generics: See go-interfaces when deciding whether an interface already models the shared behavior without generics
- Type declarations: See go-declarations when defining new types, type aliases, or choosing between type definitions and aliases
- Documenting generic APIs: See go-documentation when writing doc comments and runnable examples for generic functions
- Naming type parameters: See go-naming when choosing names for type parameters or constraint interfaces
Go Interfaces and Composition
Resource Routing
scripts/check-interface-compliance.sh- Run as a heuristic to find exported interfaces that may need compile-time assertions.scripts/check-interface-compliance.go- Implementation helper invoked bycheck-interface-compliance.sh; patch this when changing method-set analysis.references/EMBEDDING.md- Read when embedding interfaces or structs in public APIs.references/RECEIVER-TYPE.md- Read when pointer/value receivers affect interface satisfaction.
Accept Interfaces, Return Concrete Types
Interfaces belong in the package that consumes values, not the package that implements them. Return concrete (usually pointer or struct) types from constructors so new methods can be added without refactoring.
// Good: consumer defines the interface it needs
package consumer
type Thinger interface { Thing() bool }
func Foo(t Thinger) string { ... }
// Good: producer returns concrete type
package producer
type Thinger struct{ ... }
func (t Thinger) Thing() bool { ... }
func NewThinger() Thinger { return Thinger{ ... } }
// Bad: producer defines and returns its own interface
package producer
type Thinger interface { Thing() bool }
type defaultThinger struct{ ... }
func NewThinger() Thinger { return defaultThinger{ ... } }
Do not define interfaces before they are used. Without a realistic example of usage, it is too difficult to see whether an interface is even necessary.
Generality: Hide Implementation, Expose Interface
If a type exists only to implement an interface with no exported methods beyond that interface, return the interface from constructors to hide the implementation:
func NewHash() hash.Hash32 {
return &myHash{} // unexported type
}
Benefits: implementation can change without affecting callers, substituting algorithms requires only changing the constructor call.
Type Assertions: Comma-Ok Idiom
Without checking, a failed assertion causes a runtime panic. Always use the comma-ok idiom to test safely:
str, ok := value.(string)
if ok {
fmt.Printf("string value is: %q\n", str)
}
To check if a value implements an interface:
if _, ok := val.(json.Marshaler); ok {
fmt.Printf("value %v implements json.Marshaler\n", val)
}
Type Switch
It's idiomatic to reuse the variable name (t := t.(type)) — the variable has
the correct type in each case branch. When a case lists multiple types
(case int, int64:), the variable has the interface type.
Embedding
Avoid embedding types in public structs — the inner type's full method set becomes part of your public API. Use unexported fields instead.
Interface Satisfaction Checks
Use a blank identifier assignment to verify a type implements an interface at compile time:
var _ json.Marshaler = (*RawMessage)(nil)
This causes a compile error if *RawMessage doesn't implement json.Marshaler.
Use this pattern when:
- There are no static conversions that would verify the interface automatically
- The type must satisfy an interface for correct behavior (e.g., custom JSON marshaling)
- Interface changes should break compilation, not silently degrade
Don't add these checks for every interface — only when no other static conversion would catch the error.
Validation: After defining interfaces or implementations, run
bash scripts/check-interface-compliance.shto verify all concrete types have compile-timevar _ I = (*T)(nil)checks.
Receiver Type
If in doubt, use a pointer receiver. Don't mix receiver types on a single
type — if any method needs a pointer, use pointers for all methods. Use value
receivers only for small, immutable types (Point, time.Time) or basic types.
Quick Reference
| Concept | Pattern | Notes |
|---|---|---|
| Consumer owns interface | Define interfaces where used | Not in the implementing package |
| Safe type assertion | v, ok := x.(Type) | Returns zero value + false |
| Type switch | switch v := x.(type) | Variable has correct type per case |
| Interface embedding | type RW interface { Reader; Writer } | Union of methods |
| Struct embedding | type S struct { *T } | Promotes T's methods |
| Interface check | var _ I = (*T)(nil) | Compile-time verification |
| Generality | Return interface from constructor | Hide implementation |
Related Skills
- Interface naming: See go-naming when naming interfaces (the
-ersuffix convention) or choosing receiver names - Error types: See go-error-handling when implementing the
errorinterface, custom error types, orerrors.Asmatching - Generics vs interfaces: See go-generics when deciding whether generics are needed or an interface already suffices
- Functional options: See go-functional-options when using an interface-based Option pattern for flexible constructors
- Defensive boundaries: See go-defensive when interface assertions are one part of a broader API-boundary hardening pass
Go Linting
Core Principle
More important than any "blessed" set of linters: lint consistently across a codebase.
Consistent linting helps catch common issues and establishes a high bar for code quality without being unnecessarily prescriptive.
Resource Routing
scripts/setup-lint.sh- Run when generating a.golangci.yml, validating the first lint pass, or producing JSON metadata.assets/golangci.yml- Use as the v2 golangci-lint baseline for established projects.
Setup Procedure
- Create
.golangci.ymlwithscripts/setup-lint.shor copyassets/golangci.yml - Run
golangci-lint run ./... - If errors appear, fix them category by category (formatting first, then vet, then style)
- Re-run until clean
After generating .golangci.yml, run golangci-lint config verify --config .golangci.yml
to verify the configuration schema before relying on lint results.
Minimum Recommended Linters
These linters catch the most common issues while maintaining a high quality bar:
| Linter | Purpose |
|---|---|
| errcheck | Ensure errors are handled |
| goimports | Format code and manage imports |
| revive | Common style mistakes (modern replacement for golint) |
| govet | Analyze code for common mistakes |
| staticcheck | Various static analysis checks |
Note:
reviveis the modern, faster successor to the now-deprecatedgolint.
Lint Runner: golangci-lint
Use golangci-lint as your lint runner. See the example .golangci.yml from uber-go/guide.
Example Configuration
Use assets/golangci.yml as the maintained example. It targets
golangci-lint v2 (verified with 2.10.1 on 2026-06-19), keeps goimports
under formatters, and enables the core linters plus common production
additions.
Running
# Install the version this skill's config is verified against
go install github.com/golangci/golangci-lint/v2/cmd/golangci-lint@v2.10.1
# Run all linters
golangci-lint run
# Run on specific paths
golangci-lint run ./pkg/...
Additional Recommended Linters
Beyond the minimum set, consider these for production projects:
| Linter | Purpose | When to enable |
|---|---|---|
| gosec | Security vulnerability detection | Always for services handling user input |
| ineffassign | Detect ineffectual assignments | Always — catches dead code |
| misspell | Correct common misspellings in comments/strings | Always |
| gocyclo | Cyclomatic complexity threshold | When functions exceed ~15 complexity |
| exhaustive | Ensure switch covers all enum values | When using iota enums |
| bodyclose | Detect unclosed HTTP response bodies | Always for HTTP client code |
Nolint Directives
When suppressing a lint finding, always explain why:
//nolint:errcheck // fire-and-forget logging; error is not actionable
_ = logger.Sync()
Rules:
- Use
//nolint:lintername— never bare//nolint - Place the comment on the same line as the finding
- Include a justification after
//
CI/CD Integration
Run golangci-lint run ./... in CI after tests. Pin the golangci-lint version
used by CI so local and release behavior do not drift.
Pre-commit Hook
#!/bin/sh
# .git/hooks/pre-commit
golangci-lint run --new-from-rev=HEAD~1
Use --new-from-rev to lint only changed code, keeping the feedback loop fast.
Quick Reference
| Task | Command/Action |
|---|---|
| Install golangci-lint | go install github.com/golangci/golangci-lint/v2/cmd/golangci-lint@v2.10.1 |
| Run linters | golangci-lint run |
| Run on path | golangci-lint run ./pkg/... |
| Config file | .golangci.yml in project root |
| CI integration | Run golangci-lint run in pipeline |
| Nolint directives | //nolint:name // reason — never bare //nolint |
| CI integration | Use golangci/golangci-lint-action for GitHub Actions |
| Pre-commit | golangci-lint run --new-from-rev=HEAD~1 |
Linter Selection Guidelines
| When you need... | Use |
|---|---|
| Error handling coverage | errcheck |
| Import formatting | goimports |
| Style consistency | revive |
| Bug detection | govet, staticcheck |
| All of the above | golangci-lint with config |
Related Skills
- Style foundations: See go-style-core when resolving style questions that linters enforce (formatting, nesting, naming)
- Code review: See go-code-review when combining linter output with a manual review checklist
- Error handling: See go-error-handling when errcheck flags unhandled errors and you need to decide how to handle them
- Testing: See go-testing when running linters alongside tests in CI pipelines
Go Logging
Compatibility:
log/slogrequires Go 1.21+;testing/slogtestrequires Go 1.22+.
Resource Routing
references/LEVELS-AND-CONTEXT.md- Read when choosing log levels, deciding logger-in-context versus explicit parameters, or excluding sensitive fields.references/LOGGING-PATTERNS.md- Read when configuring slog handlers, logging HTTP requests, testing handlers, or migrating fromlog.Printf.
Core Principle
Logs are for operators, not developers. Every log line should help someone diagnose a production issue. If it doesn't serve that purpose, it's noise.
Choosing a Logger
Normative: Use
log/slogfor new Go code.
slog is structured, leveled, and in the standard library (Go 1.21+). It
covers the vast majority of production logging needs.
Which logger?
├─ New production code → log/slog
├─ Trivial CLI / one-off → log (standard)
└─ Measured perf bottleneck → zerolog or zap (benchmark first)
Do not introduce a third-party logging library unless profiling shows slog
is a bottleneck in your hot path. When you do, keep the same structured
key-value style.
Structured Logging
Normative: Always use key-value pairs. Never interpolate values into the message string.
The message is a static description of what happened. Dynamic data goes in key-value attributes:
// Good: static message, structured fields
slog.Info("order placed", "order_id", orderID, "total", total)
// Bad: dynamic data baked into the message string
slog.Info(fmt.Sprintf("order %d placed for $%.2f", orderID, total))
Key Naming
Advisory: Use
snake_casefor log attribute keys.
Keys should be lowercase, underscore-separated, and consistent across the
codebase: user_id, request_id, elapsed_ms.
Typed Attributes
For performance-critical paths, use typed constructors to avoid allocations:
slog.LogAttrs(ctx, slog.LevelInfo, "request handled",
slog.String("method", r.Method),
slog.Int("status", code),
slog.Duration("elapsed", elapsed),
)
Log Levels
Advisory: Follow these level semantics consistently.
| Level | When to use | Production default |
|---|---|---|
| Debug | Developer-only diagnostics, tracing internal state | Disabled |
| Info | Notable lifecycle events: startup, shutdown, config loaded | Enabled |
| Warn | Unexpected but recoverable: deprecated feature used, retry succeeded | Enabled |
| Error | Operation failed, requires operator attention | Enabled |
Rules of thumb:
- If nobody should act on it, it's not Error — use Warn or Info
- If it's only useful with a debugger attached, it's Debug
slog.Errorshould always include an"err"attribute
slog.Error("payment failed", "err", err, "order_id", id)
slog.Warn("retry succeeded", "attempt", n, "endpoint", url)
slog.Info("server started", "addr", addr)
slog.Debug("cache lookup", "key", key, "hit", hit)
Request-Scoped Logging
Advisory: Derive loggers from context to carry request-scoped fields.
Use middleware to enrich a logger with request ID, user ID, or trace ID, then pass the enriched logger downstream via context or as an explicit parameter. Keep the full context-key and middleware implementation in the logging patterns reference so request-scoped logging has one owner.
Log or Return, Not Both
The handle-once rule belongs to go-error-handling. In logging work, apply it by choosing either a local log-and-recover path or a return path with context, not both for the same error.
Exception: HTTP handlers and other top-of-stack boundaries may log detailed errors server-side while returning a sanitized message to the client:
if err != nil {
slog.Error("checkout failed", "err", err, "user_id", uid)
http.Error(w, "internal error", http.StatusInternalServerError)
return
}
See go-error-handling for the full handle-once pattern and error wrapping guidance.
What NOT to Log
Normative: Never log secrets, credentials, PII, or high-cardinality unbounded data.
- Passwords, API keys, tokens, session IDs
- Full credit card numbers, SSNs
- Request/response bodies that may contain user data
- Entire slices or maps of unbounded size
Quick Reference
| Do | Don't |
|---|---|
slog.Info("msg", "key", val) | log.Printf("msg %v", val) |
| Static message + structured fields | fmt.Sprintf in message |
snake_case keys | camelCase or inconsistent keys |
| Log OR return errors | Log AND return the same error |
| Derive logger from context | Create a new logger per call |
Use slog.Error with "err" attr | slog.Info for errors |
Pre-check Enabled() on hot paths | Always allocate log args |
Related Skills
- Error handling: See go-error-handling when deciding whether to log or return an error, or for the handle-once pattern
- Context propagation: See go-context when passing request-scoped values (including loggers) through context
- Performance: See go-performance when optimizing hot-path logging or reducing allocations in log calls
- Code review: See go-code-review when reviewing logging practices in Go PRs
Go Naming Conventions
Resource Routing
scripts/check-naming.sh- Run when checking SCREAMING_SNAKE_CASE constants, Get-prefixed getters, generic package names, or receivers namedthis/self.references/IDENTIFIERS.md- Read when choosing names for initialisms, exported identifiers, or package-level symbols.references/REPETITION.md- Read when names repeat package, receiver, type, or local context.references/VARIABLES.md- Read when choosing local variable names, receiver names, or loop identifiers.
Core Principle
Names should:
- Not feel repetitive when used
- Take context into consideration
- Not repeat concepts that are already clear
Naming is more art than science—Go names tend to be shorter than in other languages.
Naming Decision Flow
What are you naming?
├─ Package → Short, lowercase, singular noun (no underscores, no mixedCaps)
├─ Interface → Method name + "-er" suffix when single-method (Reader, Writer)
├─ Receiver → 1-2 letter abbreviation of type (c for Client); consistent across methods
├─ Constant → MixedCaps; use iota for enums; no ALL_CAPS
├─ Exported func → Verb or verb-phrase in MixedCaps; no Get prefix for getters
├─ Variable → Length proportional to scope distance
│ ├─ Tiny scope (1-7 lines) → single letter (i, n, r)
│ ├─ Medium scope → short word (count, buf)
│ └─ Package-level / wide → descriptive (userAccountCount)
└─ Any name → Check: does it repeat package name or context? If yes, shorten it
MixedCaps (Required)
Normative: All Go identifiers must use MixedCaps.
Underscores are allowed only in: test functions (TestFoo_InvalidInput),
generated code, and OS/cgo interop.
Package Names
Normative: Packages must be lowercase with no underscores.
Short, lowercase, singular nouns. Avoid generic names like util, common,
helper — prefer specific names: stringutil, httpauth, configloader.
// Good: user, oauth2, tabwriter
// Bad: user_service, UserService, count (shadows var)
Interface Names
Advisory: One-method interfaces use "-er" suffix.
Name one-method interfaces by the method plus -er: Reader, Writer,
Formatter. Honor canonical method names (Read, Write, Close, String)
and their signatures.
Receiver Names
Normative: Receivers must be short abbreviations, used consistently.
One or two letters abbreviating the type, consistent across all methods:
func (c *Client) Connect(), func (c *Client) Send().
Never use this or self.
Constant Names
Normative: Constants use MixedCaps, never ALL_CAPS or K prefix.
Name constants by role, not value: MaxRetries not Three,
DefaultPort not Port8080.
const MaxPacketSize = 512
const defaultTimeout = 30 * time.Second
Initialisms and Acronyms
Normative: Initialisms maintain consistent case throughout.
Initialisms (URL, ID, HTTP, API) must be all uppercase or all lowercase:
HTTPClient, userID, ParseURL() — not HttpClient, orderId, ParseUrl().
Function and Method Names
Advisory: No
Getprefix for simple accessors; use verb-like names for actions.
Getter for field owner is Owner(), not GetOwner(). Setter is
SetOwner(). Use Compute or Fetch for expensive operations.
When functions differ only by type, include type at the end:
ParseInt(), ParseInt64().
Variable Names
Variable naming balances brevity with clarity. Key principles:
- Scope-based length: Short names (
i,v) for small scopes; longer, descriptive names for larger scopes - Single-letter conventions: Use familiar patterns (
ifor index,r/wfor reader/writer) - Avoid type in name: Use
usersnotuserSlice,namenotnameString - Prefix unexported globals: Use
_prefix for package-level unexported vars/consts to prevent shadowing
for i, v := range items { ... } // small scope
pendingOrders := filterPending(orders) // larger scope
const _defaultPort = 8080 // unexported global
Avoiding Repetition
Go names should not feel repetitive when used. Consider the full context:
- Package + symbol:
widget.New()notwidget.NewWidget() - Receiver + method:
p.Name()notp.ProjectName() - Context + type: In package
sqldb, useConnectionnotDBConnection
Avoid Built-In Names
Never shadow Go's predeclared identifiers (error, string, len, cap,
append, copy, new, make, etc.) as variable, parameter, or type names.
For detailed guidance: See go-declarations — "Avoid Using Built-In Names"
section.
Quick Reference
| Element | Rule | Example |
|---|---|---|
| Package | lowercase, no underscores | package httputil |
| Exported | MixedCaps, starts uppercase | func ParseURL() |
| Unexported | mixedCaps, starts lowercase | func parseURL() |
| Receiver | 1-2 letter abbreviation | func (c *Client) |
| Constant | MixedCaps, never ALL_CAPS | const MaxSize = 100 |
| Initialism | consistent case | userID, XMLAPI |
| Variable | length ~ scope size | i (small), userCount (large) |
| Built-in names | Never shadow predeclared identifiers | See go-declarations |
Validation: After renaming identifiers, run
bash scripts/check-naming.shto verify no naming anti-patterns remain. Then rungo build ./...to confirm the rename didn't break anything.
Related Skills
- Interface naming: See go-interfaces when naming interfaces with the
-ersuffix or choosing receiver types - Package naming: See go-packages when naming packages, avoiding
util/common, or resolving import collisions - Error naming: See go-error-handling when naming sentinel errors (
ErrFoo) or custom error types - Declaration scope: See go-declarations when variable name length depends on scope or when avoiding built-in shadowing
- Style principles: See go-style-core when balancing clarity vs concision in identifier names
Go Packages and Imports
Resource Routing
references/IMPORTS.md- Read when grouping imports, using blank imports, dot imports, or import aliases.references/PACKAGE-SIZE.md- Read when splitting packages, avoidinginit, structuringmain, or designing CLI flags/subcommands.
When this skill does NOT apply: For naming individual identifiers within a package, see go-naming. For organizing functions within a single file, see go-functions. For configuring linters that enforce import rules, see go-linting.
Package Organization
Avoid Util Packages
Package names should describe what the package provides. Avoid generic names
like util, helper, common — they obscure meaning and cause import
conflicts.
// Good: Meaningful package names
db := spannertest.NewDatabaseFromFile(...)
_, err := f.Seek(0, io.SeekStart)
// Bad: Vague names obscure meaning
db := test.NewDatabaseFromFile(...)
_, err := f.Seek(0, common.SeekStart)
Generic names can be used as part of a name (e.g., stringutil) but should
not be the entire package name.
Package Size
| Question | Action |
|---|---|
| Can you describe its purpose in one sentence? | No → split by responsibility |
| Do files never share unexported symbols? | Those files could be separate packages |
| Distinct user groups use different parts? | Split along user boundaries |
| Godoc page overwhelming? | Split to improve discoverability |
Do NOT split just because a file is long, to create single-type packages, or if it would create circular dependencies.
Imports
Imports are organized in groups separated by blank lines. Standard library packages always come first. Use goimports to manage this automatically.
import (
"fmt"
"os"
"github.com/foo/bar"
"rsc.io/goversion/version"
)
Quick rules:
| Rule | Guidance |
|---|---|
| Grouping | stdlib first, then external. Extended: stdlib → other → protos → side-effects |
| Renaming | Avoid unless collision. Rename the most local import. Proto packages get pb suffix |
Blank imports (import _) | Only in main packages or tests |
Dot imports (import .) | Never use, except for circular-dependency test files |
Avoid init()
Avoid init() where possible. When unavoidable, it must be:
- Completely deterministic
- Independent of other
init()ordering - Free of environment state (env vars, working dir, args)
- Free of I/O (filesystem, network, system calls)
Acceptable uses: complex expressions that can't be single assignments,
pluggable hooks (e.g., database/sql dialects), deterministic precomputation.
Exit in Main
Call os.Exit or log.Fatal* only in main(). All other functions should
return errors.
Why: Non-obvious control flow, untestable, defer statements skipped.
Best practice: Use the run() pattern — extract logic into
func run() error, call from main() with a single exit point:
func main() {
if err := run(); err != nil {
log.Fatal(err)
}
}
Command-Line Flags
Advisory: Define flags only in
package main.
- Flag names use
snake_case:--output_dirnot--outputDir - Libraries should accept configuration as parameters, not read flags directly — this keeps them testable and reusable
- Prefer the standard
flagpackage; usepflagonly when POSIX conventions (double-dash, single-char shortcuts) are required
// Good: Flag in main, passed as parameter to library
func main() {
outputDir := flag.String("output_dir", ".", "directory for output files")
flag.Parse()
if err := mylib.Generate(*outputDir); err != nil {
log.Fatal(err)
}
}
Related Skills
- Package naming: See go-naming when choosing package names, avoiding stuttering, or naming exported symbols
- Error handling across packages: See go-error-handling when wrapping errors at package boundaries with
%wvs%v - Import linting: See go-linting when configuring goimports local-prefixes or enforcing import grouping
- Global state: See go-defensive when replacing
init()with explicit initialization or avoiding mutable globals
Go Performance Patterns
Resource Routing
scripts/bench-compare.sh- Run when comparing benchmark results, saving baselines, or producing JSON benchmark metadata.references/BENCHMARKS.md- Read when writing benchmarks, using benchstat, or profiling with pprof.references/STRING-OPTIMIZATION.md- Read when optimizing string conversion, concatenation, or byte/string boundaries.
Performance-specific guidelines apply only to the hot path. Don't prematurely optimize—focus these patterns where they matter most.
Prefer strconv over fmt
When converting primitives to/from strings, strconv is faster than fmt:
s := strconv.Itoa(rand.Int()) // ~2x faster than fmt.Sprint()
| Approach | Speed | Allocations |
|---|---|---|
fmt.Sprint | 143 ns/op | 2 allocs/op |
strconv.Itoa | 64.2 ns/op | 1 allocs/op |
Avoid Repeated String-to-Byte Conversions
Convert a fixed string to []byte once outside the loop:
data := []byte("Hello world")
for b.Loop() { // Go 1.24+; use b.N loops only for older Go
w.Write(data) // ~7x faster than []byte("...") each iteration
}
Prefer Specifying Container Capacity
Specify container capacity where possible to allocate memory up front. This minimizes subsequent allocations from copying and resizing as elements are added.
Map Capacity Hints
Provide capacity hints when initializing maps with make():
m := make(map[string]os.DirEntry, len(files))
Note: Unlike slices, map capacity hints do not guarantee complete preemptive allocation—they approximate the number of hashmap buckets required.
Slice Capacity
Provide capacity hints when initializing slices with make(), particularly when appending:
data := make([]int, 0, size)
Unlike maps, slice capacity is not a hint—the compiler allocates exactly that much memory. Subsequent append() operations incur zero allocations until capacity is reached.
| Approach | Time (100M iterations) |
|---|---|
| No capacity | 2.48s |
| With capacity | 0.21s |
The capacity version is ~12x faster due to zero reallocations during append.
Pass Values
Don't pass pointers as function arguments just to save a few bytes. If a function refers to its argument x only as *x throughout, then the argument shouldn't be a pointer.
func process(s string) { // not *string — strings are small fixed-size headers
fmt.Println(s)
}
Common pass-by-value types: string, io.Reader, small structs.
Exceptions:
- Large structs where copying is expensive
- Small structs that might grow in the future
String Concatenation
Choose the right strategy based on complexity:
| Method | Best For |
|---|---|
+ | Few strings, simple concat |
fmt.Sprintf | Formatted output with mixed types |
strings.Builder | Loop/piecemeal construction |
strings.Join | Joining a slice |
| Backtick literal | Constant multi-line text |
Benchmarking and Profiling
Always measure before and after optimizing. Use Go's built-in benchmark framework and profiling tools.
go test -bench=. -benchmem -count=10 ./...
Validation: After applying optimizations, run
bash scripts/bench-compare.shto measure the actual impact. Only keep optimizations with measurable improvement.
Quick Reference
| Pattern | Bad | Good | Improvement |
|---|---|---|---|
| Int to string | fmt.Sprint(n) | strconv.Itoa(n) | ~2x faster |
Repeated []byte | []byte("str") in loop | Convert once outside | ~7x faster |
| Map initialization | make(map[K]V) | make(map[K]V, size) | Fewer allocs |
| Slice initialization | make([]T, 0) | make([]T, 0, cap) | ~12x faster |
| Small fixed-size args | *string, *io.Reader | string, io.Reader | No indirection |
| Simple string join | s1 + " " + s2 | (already good) | Use + for few strings |
| Loop string build | Repeated += | strings.Builder | O(n) vs O(n²) |
Related Skills
- Data structures: See go-data-structures when choosing between slices, maps, and arrays, or understanding allocation semantics
- Declaration patterns: See go-declarations when using
makewith capacity hints or initializing maps and slices - Concurrency: See go-concurrency when parallelizing work across goroutines or using sync.Pool for buffer reuse
- Style principles: See go-style-core when deciding whether an optimization is worth the readability cost
Go Style Core Principles
Resource Routing
references/PRINCIPLES.md- Read when resolving conflicts between clarity, simplicity, concision, maintainability, and consistency.references/FORMATTING.md- Read when handling gofmt, line breaks, whitespace, comments, or semicolons.
Style Principles (Priority Order)
When writing readable Go code, apply these principles in order of importance:
Priority Order
- Clarity — Can a reader understand the code without extra context?
- Simplicity — Is this the simplest way to accomplish the goal?
- Concision — Does every line earn its place?
- Maintainability — Will this be easy to modify later?
- Consistency — Does it match surrounding code and project conventions?
Formatting
Run gofmt — no exceptions. There is no rigid line length limit, but Uber suggests a soft limit of 99 characters. Break by semantics, not length — refactor rather than just wrap.
Reduce Nesting
Handle error cases and special conditions first. Return early or continue the loop to keep the "happy path" unindented.
// Bad: Deeply nested
for _, v := range data {
if v.F1 == 1 {
v = process(v)
if err := v.Call(); err == nil {
v.Send()
} else {
return err
}
} else {
log.Printf("Invalid v: %v", v)
}
}
// Good: Flat structure with early returns
for _, v := range data {
if v.F1 != 1 {
log.Printf("Invalid v: %v", v)
continue
}
v = process(v)
if err := v.Call(); err != nil {
return err
}
v.Send()
}
Unnecessary Else
If a variable is set in both branches of an if, use default + override pattern.
// Bad: Setting in both branches
var a int
if b {
a = 100
} else {
a = 10
}
// Good: Default + override
a := 10
if b {
a = 100
}
Naked Returns
A return statement without arguments returns the named return values. This is
known as a "naked" return.
func split(sum int) (x, y int) {
x = sum * 4 / 9
y = sum - x
return // returns x, y
}
Guidelines for Naked Returns
- OK in small functions: Naked returns are fine in functions that are just a handful of lines
- Be explicit in medium+ functions: Once a function grows to medium size, be explicit with return values for clarity
- Don't name results just for naked returns: Clarity of documentation is always more important than saving a line or two
// Good: Small function, naked return is clear
func minMax(a, b int) (min, max int) {
if a < b {
min, max = a, b
} else {
min, max = b, a
}
return
}
// Good: Larger function, explicit return
func processData(data []byte) (result []byte, err error) {
result = make([]byte, 0, len(data))
for _, b := range data {
if b == 0 {
return nil, errors.New("null byte in data")
}
result = append(result, transform(b))
}
return result, nil // explicit: clearer in longer functions
}
See go-documentation for guidance on Named Result Parameters.
Semicolons
Go's lexer automatically inserts semicolons after any line whose last token is
an identifier, literal, or one of: break continue fallthrough return ++ -- ) }.
This means opening braces must be on the same line as the control structure:
// Good: brace on same line
if i < f() {
g()
}
// Bad: brace on next line — lexer inserts semicolon after f()
if i < f() // wrong!
{ // wrong!
g()
}
Idiomatic Go only has explicit semicolons in for loop clauses and to separate
multiple statements on a single line.
Quick Reference
| Principle | Key Question |
|---|---|
| Clarity | Can a reader understand what and why? |
| Simplicity | Is this the simplest approach? |
| Concision | Is the signal-to-noise ratio high? |
| Maintainability | Can this be safely modified later? |
| Consistency | Does this match surrounding code? |
Related Skills
- Naming conventions: See go-naming when applying MixedCaps, choosing identifier names, or resolving naming debates
- Error flow: See go-error-handling when structuring error-first guard clauses or reducing nesting via early returns
- Documentation: See go-documentation when writing doc comments, named return parameters, or package-level docs
- Linting enforcement: See go-linting when automating style checks with golangci-lint or configuring CI
- Code review: See go-code-review when applying style principles during a systematic code review
- Logging style: See go-logging when reviewing logging practices, choosing between log and slog, or structuring log output
Go Testing
Compatibility: Diff examples may use
github.com/google/go-cmp.
Resource Routing
scripts/gen-table-test.sh- Run when generating a table-driven test scaffold.assets/table-test-template.go- Use as a copyable table-test starting point.references/TABLE-DRIVEN-TESTS.md- Read when choosing table tests, subtests, or parallel test patterns.references/TEST-HELPERS.md- Read when writing helpers, fixtures, cleanup, or test doubles.references/TEST-ORGANIZATION.md- Read when structuring packages, black-box tests, or larger test suites.references/VALIDATION-APIS.md- Read when choosingt.Error,t.Fatal,cmp.Diff, or assertion style.references/INTEGRATION.md- Read when testing external services, HTTP handlers, databases, or long-running setup.
Quick Reference
| Pattern | Use When |
|---|---|
t.Error | Default — report failure, keep running |
t.Fatal | Setup failed or continuing is meaningless |
cmp.Diff | Comparing structs, slices, maps, protos |
| Table-driven | Many cases share identical logic |
| Subtests | Need filtering, parallel execution, or naming |
t.Helper() | Any test helper function (call as first statement) |
t.Cleanup() | Teardown in helpers instead of defer |
Useful Test Failures
Normative: Test failures must be diagnosable without reading the test source.
Every failure message must include: function name, inputs, actual (got), and
expected (want). Use the format YourFunc(%v) = %v, want %v.
// Good:
t.Errorf("Add(2, 3) = %d, want %d", got, 5)
// Bad: Missing function name and inputs
t.Errorf("got %d, want %d", got, 5)
Always print got before want: got %v, want %v — never reversed.
No Assertion Libraries
Normative: Do not use assertion libraries. Use
cmp.Difffor complex comparisons.
if diff := cmp.Diff(want, got); diff != "" {
t.Errorf("GetPost() mismatch (-want +got):\n%s", diff)
}
For protocol buffers, add protocmp.Transform() as a cmp option. Always
include the direction key (-want +got) in diff messages. Avoid comparing
JSON/serialized output — compare semantically instead.
t.Error vs t.Fatal
Normative: Use
t.Errorby default to report all failures in one run. Uset.Fatalonly when continuing is impossible.
Choose t.Fatal when:
- Setup fails (DB connection, file load)
- The next assertion depends on the previous one succeeding (e.g., decode after encode)
Never call t.Fatal/t.FailNow from a goroutine other than the test
goroutine — use t.Error instead.
Table-Driven Tests
See
assets/table-test-template.gowhen scaffolding a new table-driven test and need the canonical struct, loop, and subtest layout.
Advisory: Use table-driven tests when many cases share identical logic.
Use table tests when: all cases run the same code path with no conditional
setup, mocking, or assertions. A single shouldErr bool is acceptable.
Don't use table tests when: cases need complex setup, conditional mocking, or multiple branches — write separate test functions instead.
Key rules:
- Use field names when cases span many lines or have same-type adjacent fields
- Include inputs in failure messages — never identify rows by index
Validation: After generating or modifying tests, run
go test -run TestXxx -vto verify the tests compile and pass. Fix any compilation errors before proceeding.
Test Helpers
Normative: Test helpers must call
t.Helper()first and uset.Cleanup()for teardown.
func setupTestDB(t *testing.T) *sql.DB {
t.Helper()
db, err := sql.Open("sqlite3", ":memory:")
if err != nil {
t.Fatalf("Could not open database: %v", err)
}
t.Cleanup(func() { db.Close() })
return db
}
Test Error Semantics
Advisory: Test error semantics, not error message strings.
// Bad: Brittle string comparison
if err.Error() != "invalid input" { ... }
// Good: Semantic check
if !errors.Is(err, ErrInvalidInput) { ... }
For simple presence checks when specific semantics don't matter:
if gotErr := err != nil; gotErr != tt.wantErr {
t.Errorf("f(%v) error = %v, want error presence = %t", tt.input, err, tt.wantErr)
}
Related Skills
- Error testing: See go-error-handling when testing error semantics with
errors.Is/errors.Asor sentinel errors - Interface mocking: See go-interfaces when creating test doubles by implementing interfaces at the consumer side
- Naming test functions: See go-naming when naming test functions, subtests, or test helper utilities
- Linter integration: See go-linting when running linters alongside tests in CI or pre-commit hooks
Sponsors
Details
- Marketplace
- cxuu/golang-skills
- Category
- Community