cxuu avatar

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-skills

Run it inside Claude Code after adding the marketplace with /plugin marketplace add cxuu/golang-skills.

Contents

Discovered from source

Skills 20

Go Code Review Checklist

Compatibility: references/WEB-SERVER.md uses log/slog examples 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.md when formatting the output of a code review to ensure consistent structure with Must Fix / Should Fix / Nits severity grouping.

  1. Run gofmt -d . and go vet ./... to catch mechanical issues first
  2. Read the diff file-by-file; for each file, check the categories below in order
  3. Flag issues with specific line references and the rule name
  4. After reviewing all files, re-read flagged items to verify they're genuine issues
  5. 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 gofmt or goimports → 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 MixedCaps or mixedCaps, never underscores; unexported is maxLength not MAX_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 (c for Client); no this, self, me; consistent across methods → go-naming
  • Package names: No stuttering (use chubby.File not chubby.ChubbyFile); avoid util, 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) over t := []string{} (non-nil zero-length) → go-data-structures
  • Copying: Be careful copying structs with pointer/slice fields; don't copy *T methods' receivers by value → go-data-structures

Security

  • Crypto rand: Use crypto/rand for keys, not math/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/type in parenthesized blocks; separate unrelated → go-declarations
  • var vs :=: Use var for 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; var for zero structs → go-declarations
  • Use any: Prefer any over interface{} 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 f for go 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 string not *string for small fixed-size types → go-performance
  • String concatenation: + for simple; fmt.Sprintf for formatting; strings.Builder for loops → go-performance

Logging

  • Use slog: New code uses log/slog, not log or fmt.Println for 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 Example functions 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/atomic where 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

  1. Every goroutine needs a stop mechanism — a predictable end time, a cancellation signal, or both
  2. Code must be able to wait for the goroutine to finish
  3. No goroutines in init() — expose lifecycle methods (Close, Stop, Shutdown) instead
  4. 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.

BenefitWhy
Localized goroutinesLifetimes easier to reason about
Avoids leaks and racesEasier to prevent resource leaks and data races
Easier to testCheck input/output without polling
Caller flexibilityCaller 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:

  1. Read vs mutating is unclear — e.g., a Lookup that mutates LRU state
  2. API provides synchronization — e.g., thread-safe clients
  3. 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

Go Context Usage

Compatibility: context has 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:

  1. Function parameters — most explicit and type-safe
  2. Receiver — for data that belongs to the type
  3. Globals — for truly global configuration (use sparingly)
  4. 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:

  1. The declaration is in the same scope as the existing v
  2. The value is assignable to v
  3. 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 — i is 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

PatternGo Idiom
If initializationif err := f(); err != nil { }
Early returnOmit else when if body returns
Redeclaration:= reassigns if same scope + new var
Shadowing trap:= in inner scope creates new variable
Parallel assignmenti, j = i+1, j-1
Expression-less switchswitch { case cond: }
Comma casescase 'a', 'b', 'c':
No fallthroughDefault behavior (explicit fallthrough if needed)
Break from loop in switchbreak Label
Discard value_, err := f()
Side-effect importimport _ "pkg"
Interface checkRoute 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

TopicKey Point
SlicesAlways assign append result; nil slice preferred over []T{}
Setsmap[T]struct{} for membership-only sets
CopyingDon'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 between var, :=, 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 :=

ContextUseExample
Top-levelvar (always)var _s = F()
Local with value:=s := "foo"
Local zero-value (intentional)varvar filtered []int
Type differs from expressionvar with typevar _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 var for zero-value structs: var user User not user := User{}
  • Use &T{} over new(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

ScenarioUseExample
Empty, populated latermake(map[K]V)m := make(map[string]int)
Nil declarationvarvar m map[string]int
Fixed entries at initLiteralm := 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 new and make, 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

PatternRuleDetails
Boundary copiesCopy slices/maps on receive and returnBOUNDARY-COPYING.md
Defer cleanupdefer f.Close() right after os.OpenBelow
Interface checkCompile-time satisfaction assertionSee go-interfaces
Time typestime.Time / time.Duration, never raw intTIME-ENUMS-TAGS.md
Enum startiota + 1 so zero = invalidBelow
Crypto randcrypto/rand for keys, never math/randBelow
Must functionsOnly at init; panic on failureMUST-FUNCTIONS.md
Panic/recoverNever expose panics across packagesPANIC-RECOVER.md
Mutable globalsReplace with dependency injectionBelow

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 by check-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

  1. Begin with the name of the object being described
  2. An article ("a", "an", "the") may precede the name
  3. 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.sh to 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 main packages, use the binary name: // The seed_generator command ...
  • For long package comments, use a doc.go file

What to Document

Advisory: Document non-obvious behavior, not obvious behavior.

TopicDocument when...Skip when...
ParametersNon-obvious behavior, edge casesRestates the type signature
ContextsBehavior differs from standard cancellationStandard ctx.Err() return
ConcurrencyAmbiguous thread safety (e.g., read that mutates)Read-only is safe, mutation is unsafe
CleanupAlways document resource release—
ErrorsSentinel values, error types (use *PathError)—
Named resultsMultiple params of same type, action-oriented namesType 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 correct errors.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

TopicKey Rule
Doc commentsStart with name, use full sentences
Line length~80 chars, prioritize readability
Package commentsOne per package, above package clause
ParametersDocument non-obvious behavior only
ContextsDocument exceptions to implied behavior
ConcurrencyDocument ambiguous thread safety
CleanupAlways document resource release
ErrorsDocument sentinels and types (note pointer)
ExamplesUse runnable examples in test files
FormattingBlank 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 Example test 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 %w wrapping require Go 1.13+; structured logging examples may use log/slog from 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 by check-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 %w versus %v or crossing package boundaries.

In Go, errors are values — they are created by code and consumed by code.

Choosing an Error Strategy

  1. System boundary (RPC, IPC, storage)? → Wrap with %v to avoid leaking internals
  2. Caller needs to match specific conditions? → Sentinel or typed error, wrap with %w
  3. Caller just needs debugging context? → fmt.Errorf("...: %w", err)
  4. 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 _:

  1. Handle immediately — address the error and continue
  2. Return to caller — optionally wrapped with context
  3. In exceptional cases — log.Fatal or panic

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 typeUse
Nostaticerrors.New("message")
Nodynamicfmt.Errorf("msg: %v", val)
Yesstaticvar ErrFoo = errors.New("...")
Yesdynamiccustom 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 for errors.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.sh to detect common anti-patterns. Then run go 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.As or 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

  1. Unexported options struct - holds all configuration
  2. Exported Option interface - with unexported apply method
  3. Option types - implement the interface
  4. 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

AspectFunctional OptionsConfig Struct
ExtensibilityAdd new With* functionsAdd new fields (may break)
DefaultsBuilt into constructorZero values or separate defaults
Caller experienceOnly specify what differsMust construct entire struct
TestabilityOptions are comparableStruct comparison
ComplexityMore boilerplateSimpler 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:

  1. Testability - Options can be compared in tests and mocks
  2. Debuggability - Options can implement fmt.Stringer
  3. Flexibility - Options can implement additional interfaces
  4. 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

  • options struct is unexported
  • Option interface has unexported apply method
  • 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 Option interface 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 Option types, With* functions, or constructor behavior

External Resources

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:

  1. Functions sorted in rough call order
  2. Functions grouped by receiver
  3. Exported functions appear first, after struct/const/var definitions
  4. NewXxx/newXxx constructors appear right after the type definition
  5. 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

TopicRule
File orderingType -> constructor -> exported -> unexported -> utils
Signature wrappingAll args on own lines with trailing comma
Naked parametersAdd /* name */ comments or use custom types
Pointers to interfacesAlmost never needed; pass interfaces by value
Printf function namesEnd 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 any and 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

NameTypical Use
TGeneral type parameter
KMap key type
VMap value type
EElement/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

TopicGuidance
When to use genericsOnly when multiple types share identical logic and interfaces don't suffice
Starting pointWrite concrete code first; generalize later
NamingSingle uppercase letter (T, K, V, E)
Type aliasesSame type, alternate name; use only for migration
Constraint compositionUse ~ for underlying types, `
Common pitfallDon'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 by check-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.sh to verify all concrete types have compile-time var _ 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

ConceptPatternNotes
Consumer owns interfaceDefine interfaces where usedNot in the implementing package
Safe type assertionv, ok := x.(Type)Returns zero value + false
Type switchswitch v := x.(type)Variable has correct type per case
Interface embeddingtype RW interface { Reader; Writer }Union of methods
Struct embeddingtype S struct { *T }Promotes T's methods
Interface checkvar _ I = (*T)(nil)Compile-time verification
GeneralityReturn interface from constructorHide implementation

Related Skills

  • Interface naming: See go-naming when naming interfaces (the -er suffix convention) or choosing receiver names
  • Error types: See go-error-handling when implementing the error interface, custom error types, or errors.As matching
  • 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

  1. Create .golangci.yml with scripts/setup-lint.sh or copy assets/golangci.yml
  2. Run golangci-lint run ./...
  3. If errors appear, fix them category by category (formatting first, then vet, then style)
  4. 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:

LinterPurpose
errcheckEnsure errors are handled
goimportsFormat code and manage imports
reviveCommon style mistakes (modern replacement for golint)
govetAnalyze code for common mistakes
staticcheckVarious static analysis checks

Note: revive is the modern, faster successor to the now-deprecated golint.


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:

LinterPurposeWhen to enable
gosecSecurity vulnerability detectionAlways for services handling user input
ineffassignDetect ineffectual assignmentsAlways — catches dead code
misspellCorrect common misspellings in comments/stringsAlways
gocycloCyclomatic complexity thresholdWhen functions exceed ~15 complexity
exhaustiveEnsure switch covers all enum valuesWhen using iota enums
bodycloseDetect unclosed HTTP response bodiesAlways 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

TaskCommand/Action
Install golangci-lintgo install github.com/golangci/golangci-lint/v2/cmd/golangci-lint@v2.10.1
Run lintersgolangci-lint run
Run on pathgolangci-lint run ./pkg/...
Config file.golangci.yml in project root
CI integrationRun golangci-lint run in pipeline
Nolint directives//nolint:name // reason — never bare //nolint
CI integrationUse golangci/golangci-lint-action for GitHub Actions
Pre-commitgolangci-lint run --new-from-rev=HEAD~1

Linter Selection Guidelines

When you need...Use
Error handling coverageerrcheck
Import formattinggoimports
Style consistencyrevive
Bug detectiongovet, staticcheck
All of the abovegolangci-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/slog requires Go 1.21+; testing/slogtest requires 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 from log.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/slog for 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_case for 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.

LevelWhen to useProduction default
DebugDeveloper-only diagnostics, tracing internal stateDisabled
InfoNotable lifecycle events: startup, shutdown, config loadedEnabled
WarnUnexpected but recoverable: deprecated feature used, retry succeededEnabled
ErrorOperation failed, requires operator attentionEnabled

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.Error should 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

DoDon't
slog.Info("msg", "key", val)log.Printf("msg %v", val)
Static message + structured fieldsfmt.Sprintf in message
snake_case keyscamelCase or inconsistent keys
Log OR return errorsLog AND return the same error
Derive logger from contextCreate a new logger per call
Use slog.Error with "err" attrslog.Info for errors
Pre-check Enabled() on hot pathsAlways 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 named this/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 Get prefix 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 (i for index, r/w for reader/writer)
  • Avoid type in name: Use users not userSlice, name not nameString
  • 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() not widget.NewWidget()
  • Receiver + method: p.Name() not p.ProjectName()
  • Context + type: In package sqldb, use Connection not DBConnection

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

ElementRuleExample
Packagelowercase, no underscorespackage httputil
ExportedMixedCaps, starts uppercasefunc ParseURL()
UnexportedmixedCaps, starts lowercasefunc parseURL()
Receiver1-2 letter abbreviationfunc (c *Client)
ConstantMixedCaps, never ALL_CAPSconst MaxSize = 100
Initialismconsistent caseuserID, XMLAPI
Variablelength ~ scope sizei (small), userCount (large)
Built-in namesNever shadow predeclared identifiersSee go-declarations

Validation: After renaming identifiers, run bash scripts/check-naming.sh to verify no naming anti-patterns remain. Then run go build ./... to confirm the rename didn't break anything.

Related Skills

  • Interface naming: See go-interfaces when naming interfaces with the -er suffix 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, avoiding init, structuring main, 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

QuestionAction
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:

RuleGuidance
Groupingstdlib first, then external. Extended: stdlib → other → protos → side-effects
RenamingAvoid 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:

  1. Completely deterministic
  2. Independent of other init() ordering
  3. Free of environment state (env vars, working dir, args)
  4. 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_dir not --outputDir
  • Libraries should accept configuration as parameters, not read flags directly — this keeps them testable and reusable
  • Prefer the standard flag package; use pflag only 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 %w vs %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()
ApproachSpeedAllocations
fmt.Sprint143 ns/op2 allocs/op
strconv.Itoa64.2 ns/op1 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.

ApproachTime (100M iterations)
No capacity2.48s
With capacity0.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:

MethodBest For
+Few strings, simple concat
fmt.SprintfFormatted output with mixed types
strings.BuilderLoop/piecemeal construction
strings.JoinJoining a slice
Backtick literalConstant 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.sh to measure the actual impact. Only keep optimizations with measurable improvement.


Quick Reference

PatternBadGoodImprovement
Int to stringfmt.Sprint(n)strconv.Itoa(n)~2x faster
Repeated []byte[]byte("str") in loopConvert once outside~7x faster
Map initializationmake(map[K]V)make(map[K]V, size)Fewer allocs
Slice initializationmake([]T, 0)make([]T, 0, cap)~12x faster
Small fixed-size args*string, *io.Readerstring, io.ReaderNo indirection
Simple string joins1 + " " + s2(already good)Use + for few strings
Loop string buildRepeated +=strings.BuilderO(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 make with 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

  1. Clarity — Can a reader understand the code without extra context?
  2. Simplicity — Is this the simplest way to accomplish the goal?
  3. Concision — Does every line earn its place?
  4. Maintainability — Will this be easy to modify later?
  5. 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

PrincipleKey Question
ClarityCan a reader understand what and why?
SimplicityIs this the simplest approach?
ConcisionIs the signal-to-noise ratio high?
MaintainabilityCan this be safely modified later?
ConsistencyDoes 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 choosing t.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

PatternUse When
t.ErrorDefault — report failure, keep running
t.FatalSetup failed or continuing is meaningless
cmp.DiffComparing structs, slices, maps, protos
Table-drivenMany cases share identical logic
SubtestsNeed 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.Diff for 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.Error by default to report all failures in one run. Use t.Fatal only 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.go when 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 -v to verify the tests compile and pass. Fix any compilation errors before proceeding.


Test Helpers

Normative: Test helpers must call t.Helper() first and use t.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.As or 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