go-patterns/patterns/from-source.md

# Go Patterns (from Source)

Prescriptive patterns extracted from golang/go source.
"If writing new Go, follow these rules."

---

## Interface Design

### Single-Method Interfaces

**Rule:** Define interfaces with one method. Compose for larger
contracts.

```go
// Source: src/io/io.go
type Reader interface {
    Read(p []byte) (n int, err error)
}

type Writer interface {
    Write(p []byte) (n int, err error)
}

// Composition:
type ReadWriter interface {
    Reader
    Writer
}
```

**Why:** Single-method interfaces maximize implementability. Any type
with a `Read` method satisfies `Reader` — no explicit declaration
needed. The Go stdlib has 15 compositions of just 4 primitives in
`io/io.go`.

**When to use:** Defining extension points, function parameters,
and dependency injection boundaries.

**When NOT to use:** When the interface genuinely requires multiple
methods that always go together (e.g., `http.Handler` is one method
but `sort.Interface` is three because Len/Less/Swap are inseparable).

### Accept Interfaces, Return Structs

**Rule:** Function parameters should be interfaces. Return values
should be concrete types.

```go
// Source: src/io/io.go — Copy accepts interfaces
func Copy(dst Writer, src Reader) (written int64, err error)

// Source: src/bufio/bufio.go — NewReader returns concrete
func NewReader(rd io.Reader) *Reader
```

**Why:** Accepting interfaces means any implementation works. Returning
structs means callers get full access to methods and fields without
type assertions.

**When to use:** Public API functions that take collaborators or
return constructed objects.

**When NOT to use:** When you need to return different types based on
input (return an interface). When the concrete type is unexported
(return an interface to hide it).

---

## Error Handling

### Sentinel Errors for Known Conditions

**Rule:** Define package-level `var Err*` for conditions callers need
to check.

```go
// Source: src/path/filepath/match.go
var ErrBadPattern = errors.New("syntax error in pattern")

// Source: src/encoding/hex/hex.go
var ErrLength = errors.New("encoding/hex: odd length hex string")
```

**Why:** Callers use `errors.Is(err, filepath.ErrBadPattern)` to handle
specific cases. The error message includes the package name for
context.

**When to use:** Errors that represent a known, documented condition
that callers may want to handle differently.

**When NOT to use:** For errors that callers never need to distinguish.
For errors that carry dynamic context (use error types instead).

### Wrap with %w for Context

**Rule:** Add context when propagating errors. Use `%w` to preserve
the original.

```go
// Source: src/encoding/json/v2_decode.go
return fmt.Errorf("cannot parse %q as JSON number: %w", val, strconv.ErrSyntax)
```

**Why:** Wrapping creates a chain. Callers can `errors.Is()` to find
the root cause while seeing the full context path.

**When to use:** Every time you propagate an error up the call stack
and the caller might need to identify the root cause.

**When NOT to use:** When the original error's identity should be
hidden (use `%v` instead of `%w` to break the chain intentionally).

---

## Testing

### Table-Driven Tests

**Rule:** Use `[]struct{}` slices for test cases. Each case has a name.

```go
// Source: src/testing/testing_test.go
func TestSetenv(t *testing.T) {
    tests := []struct {
        name               string
        key                string
        initialValueExists bool
        initialValue       string
        newValue           string
    }{
        {
            name:               "initial value exists",
            key:                "GO_TEST_KEY_1",
            initialValueExists: true,
            initialValue:       "111",
            newValue:           "222",
        },
    }
    for _, tt := range tests {
        t.Run(tt.name, func(t *testing.T) {
            // ...
        })
    }
}
```

**Why:** Each case is named, making failure output clear. Adding cases
is one struct literal. The pattern is universal in Go's own tests
(1,811 test files use it).

**When to use:** Any function with 3+ meaningful input variations.
The default testing pattern in Go.

**When NOT to use:** Single-case tests. Tests where setup varies
significantly between cases (use separate test functions).

### testdata/ for Fixtures

**Rule:** Put test fixtures in a `testdata/` directory. The Go tool
ignores it.

**Why:** Convention enforced by the toolchain — `testdata/` is never
compiled. Golden files, sample inputs, and expected outputs live here.

**When to use:** Golden files, sample inputs, certificates, expected
outputs — any file your tests read but never modify.

**When NOT to use:** Generated test data (create it in TestMain or
setup).

---

## Package Organization

### Flat Packages

**Rule:** No `pkg/` wrapper. Top-level directories ARE the packages.

```
src/
├── fmt/
├── io/
├── net/
│   └── http/
├── encoding/
│   └── json/
└── internal/
```

**Why:** The import path IS the directory path. `import "fmt"` loads
`src/fmt/`. No indirection, no wrapper directories.

**When to use:** Always. Every Go project. Import path = directory.

**When NOT to use:** Never. There is no legitimate reason for a `pkg/`
directory in Go. (The `pkg/` convention from early community projects
was a mistake that the Go team never endorsed.)

### internal/ for Shared Private Code

**Rule:** Put shared utilities that shouldn't be public API in
`internal/`.

```go
// Only packages within the same tree can import this:
import "internal/singleflight"
```

**Why:** The compiler enforces the boundary. External packages get a
build error if they try to import your internals. This is stronger than
unexported identifiers (which still allow same-package access).

**When to use:** Utility code shared across packages that is NOT
ready for (or appropriate as) public API.

**When NOT to use:** Code that is stable enough for public API (promote
it). Code only used by one package (keep it unexported within that
package).

---

## Concurrency

### context.Context as First Parameter

**Rule:** Functions that do I/O or long-running work take `ctx
context.Context` as the first parameter.

```go
// Source: src/net/http (throughout)
func (c *Client) Do(req *Request) (*Response, error)
// becomes:
func (c *Client) do(ctx context.Context, req *Request) (*Response, error)
```

**Why:** Context carries cancellation, deadlines, and request-scoped
values. First-parameter position is a universal convention — every Go
developer knows to look for it there.

**When to use:** Any function that does I/O, blocks, or might be
cancelled by the caller.

**When NOT to use:** Pure computation (no I/O, no blocking). Package-
level init functions. Short-lived operations that can't be cancelled.

### Don't Start Goroutines in Libraries

**Rule:** Let the caller control concurrency. Return results; don't
spawn goroutines.

**Why:** The Go stdlib almost never starts goroutines in library code
(exception: `net/http` server). Libraries that spawn goroutines create
lifecycle management problems — who stops them? who waits for them?

**When to use:** Pure libraries that transform data or compute
results. Let callers decide on concurrency.

**When NOT to use:** Servers (http.Server manages connections).
Background work that the caller explicitly requested (provide a
`Start`/`Stop` interface).

---

## Documentation

### Package Comment in doc.go

**Rule:** Put the package overview in a `doc.go` file with a `/*...*/`
comment.

```go
// Source: src/fmt/doc.go
/*
Package fmt implements formatted I/O with functions analogous
to C's printf and scanf.

# Printing

There are four families of printing functions...
*/
package fmt
```

**Why:** Separates documentation from implementation. The `#` headings
create sections in pkg.go.dev. `doc.go` is conventional — reviewers
know where to find the overview.

**When to use:** Any package with a non-trivial API surface that
needs an overview explaining its purpose and structure.

**When NOT to use:** Small packages where the package comment fits
naturally in the main file.

### Example Functions

**Rule:** Demonstrate usage with `Example*` functions in `*_test.go`.

```go
func ExampleSprintf() {
    fmt.Println(fmt.Sprintf("Hello, %s", "world"))
    // Output: Hello, world
}
```

**Why:** Examples are tests (they run and verify output). They appear
in docs. They can't go stale because the build fails if they break.

---

## Naming

### Short Package Names

**Rule:** Package names are short, lowercase, singular nouns.

`fmt`, `io`, `net`, `os`, `sync`, `time`, `bytes`, `errors`

**Why:** Package names prefix every exported identifier. `bytes.Buffer`
reads well. `utilities.Buffer` doesn't.

**When to use:** Every package you create. Pick the shortest noun
that accurately describes the package's single responsibility.

**When NOT to use:** Never use plurals (`utils`, `helpers`, `models`).
Never use generic names that could apply to anything.

### MixedCaps, No Underscores

**Rule:** Exported = `UpperCamelCase`. Unexported = `lowerCamelCase`.
Never underscores.

```go
// Exported:
type ReadWriter interface {}
func NewReader(rd io.Reader) *Reader

// Unexported:
type call struct {}
func (g *Group) doCall(c *call, key string) {}
```

**Why:** Capitalization IS the visibility mechanism. Underscores are
reserved for test files (`_test.go`) and generated code.

### Getters Don't Say "Get"

**Rule:** A getter for field `owner` is `Owner()`, not `GetOwner()`.

**Why:** Go convention since the language spec. Setters DO say "Set":
`SetOwner()`.

---

## Smells

### go:linkname (Escape Hatch Abuse)

```go
//go:linkname localFunction remote/package.Function
```

1,711 uses in Go's own source — but the team is actively removing them.
Third-party packages using go:linkname to access stdlib internals are
explicitly unsupported and will break on upgrade.

**Lesson:** If you need go:linkname, your API boundary is wrong.
Redesign the interface instead.

### TODO Without Owner

```go
// TODO: fix this later       ← smell
// TODO(gri): fix this later  ← correct
```

The Go team's 3,428 TODOs all have owners. An unowned TODO is
unaccountable — no one will fix it because no one owns it.

### Huge Files (proc.go = 8,156 lines)

Even Go's own scheduler is a single 8K-line file. This isn't a pattern
to copy — it's a known limitation. The Go team keeps it together
because splitting would break the scheduler's mental model, not because
one file is ideal.

**Lesson:** If your file is >1000 lines, question whether it's a real
unit or just accumulated code. The scheduler has an excuse. Your CRUD
handler doesn't.

### Generated Code Without Generator

If you check in generated code, also check in the generator (or
clearly document how to regenerate). Go's SSA rewrite rules have
generators alongside them. Generated code without visible generators
becomes unmaintainable magic.

<!-- PATTERN_COMPLETE -->