go-code-style

Go Code Style

gofmt handles the mechanical layout. This skill covers the decisions a formatter cannot make: where to break complexity, when to invert an if, when a switch beats an else if chain, and how to pick value vs pointer arguments. The rule of thumb is the Go Proverb: clear is better than clever.

Core Rules

1. Run gofmt/goimports. No exceptions, no debates.
2. Handle errors and edge cases first, return early, keep the happy path at minimum indentation.
3. Eliminate unnecessary else when the if body ends in return/break/continue.
4. Prefer switch over if/else if chains that compare the same value.
5. Initialize slices and maps explicitly, never let a nil map reach a write.
6. Pass small values; pass pointers when mutating or when the type is large (~128B+).

Style Priority Order

Apply in this order when two principles collide.

Priority	Question	Beats
1. Clarity	Can a reader understand intent without extra context?	everything else
2. Simplicity	Is this the simplest expression of the idea?	concision, consistency
3. Concision	Does every line earn its place?	consistency
4. Maintainability	Will this be safe to modify?	consistency
5. Consistency	Does it match nearby code?	—

A "consistent" piece of bad code is still bad code. Clarity wins.

Read references/formatting-and-layout.md for line-breaking, multi-line signatures, file/declaration order.

Control Flow

Early return: keep the happy path flat

func process(data []byte) (*Result, error) {
    if len(data) == 0 {
        return nil, errors.New("empty data")
    }
    parsed, err := parse(data)
    if err != nil {
        return nil, fmt.Errorf("parsing: %w", err)
    }
    return transform(parsed), nil
}

No unnecessary else

When the if body unconditionally exits (return/break/continue), drop the else. For assignments, prefer default-then-override: