Rodin
11 KiB
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.
// 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.
// 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.
// 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.
// 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.
// 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/.
// 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.
// 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.
// 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.
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.
// 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: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
// 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.