Go Engineering

Go Engineering

Guidance for producing Go that reads like it belongs in the standard library: clear, small, boring, and easy to delete.

Scope

Three kinds of correctness, and this skill owns one and a half of them.

That last row is a hard boundary, not a weakness to apologize for. Code can be flawless by every rule in this skill and still compute the wrong answer. When reviewing, say plainly that you have checked structure and idiom, and that whether the behavior is correct is a separate question the tests must answer.

Two corollaries:

• Don't claim a clean review means the code works. It means the code is well-formed.
• Don't stretch for semantic findings to seem thorough. If the logic looks wrong, say so as an ordinary observation, not as a finding from this skill.

How to use this skill

1. Run the tooling first. Most style questions are already answered by gofmt, go vet, and the project's own golangci-lint config. Don't hand-argue what a linter can decide. See references/linting.md.
2. Match the surrounding code. Local consistency beats a marginal improvement that makes a file internally inconsistent.
3. Load the reference file for the decision you're actually making (routing table below). Don't read all of them.
4. Apply the tiers honestly (next section). Don't escalate taste into law.

Normativity tiers

This skill labels guidance so you can tell settled practice from opinion. When you give advice or review code, carry the tier with you.

Three failure modes to avoid:

• Inventing rules. If none of the sources say it and it isn't tool-enforced, it's [Judgment]. Say so.
• Applying Google-internal conventions to public code. Several rules in the Google guide exist for Google's monorepo and internal libraries and do not generalize. They are marked Google-internal throughout and catalogued in references/sources.md.
• Citing stale advice. Effective Go and Go Code Review Comments predate generics, errors.Is/As, log/slog, and Go 1.22 loop semantics. See references/modern-go.md before repeating pre-1.18 advice.

Style priorities

When two good options conflict, resolve in this order (Google Go Style Guide):

1. Clarity — the code's purpose and rationale are clear to the reader.
2. Simplicity — it accomplishes its goal the simplest way.
3. Concision — high signal-to-noise ratio.
4. Maintainability — it can be changed easily and correctly.
5. Consistency — it looks like the rest of the codebase.

This is a tiebreaker order, not a scoring function. Concision never justifies obscurity; consistency never justifies propagating a bug.

Routing

The short list

The rules that come up constantly. Everything here is [Rule] unless marked.

Formatting and naming

• All code is gofmt-clean. No exceptions, including generated code.
• MixedCaps / mixedCaps, never under_scores or ALL_CAPS — constants included.
• Initialisms keep uniform case: URL, ID, HTTP, userID, parseURL. Never Url, Id.
• Package names are short, lowercase, no underscores, and not util, common, base, helpers, or misc.
• Don't stutter: http.Server, not http.HTTPServer. Callers already type the package name.
• No Get prefix on getters: u.Name(), not u.GetName().
• Receiver names are one or two letters, consistent across every method on the type. Never this, self, or me.
• Variable name length scales with scope: i in a three-line loop, remainingRetries at package level.

Errors

• error is the last return value. nil means success. [Rule]
• Error strings are lowercase and have no trailing punctuation — they get embedded in longer messages. Exception: strings starting with an exported name, proper noun, or acronym.
• Never silently discard an error with _. Handle it, return it, or explain in a comment why dropping it is correct.
• Don't use panic for ordinary failure. Errors are values; return them.
• Keep the happy path at minimal indentation — handle the error and return early, no else block.
• No in-band error values (-1, "", nil meaning "not found"). Return an extra error or bool.

Types and APIs

• Interfaces belong in the consumer package, not the implementation's. Don't define an interface before there's a real second use or a real boundary.
• Interfaces should be small. One or two methods is normal.
• Don't pass pointers just to avoid copying a few bytes. Pass a pointer when you need mutation, identity, nilability, or the value is genuinely large.
• Don't mix value and pointer receivers on one type. [Convention]
• Design types whose zero value is useful (sync.Mutex, bytes.Buffer).
• Use any, not interface{}, in new code.

Concurrency

• context.Context is the first parameter, named ctx. Never store one in a struct field. Never define a custom context type or a context-like interface. [Rule — the Google guide states this one admits no exceptions]
• When you start a goroutine, it must be obvious when and how it exits. Unbounded or undocumented goroutine lifetimes are a defect.
• Prefer synchronous functions. Let the caller add concurrency; they can't remove yours.
• Use crypto/rand, never math/rand, for keys, tokens, nonces, or session IDs.

Testing

• Failure messages say what was called, with what input, what you got, and what you wanted — got before want.
• Tests keep going: prefer t.Error over t.Fatal unless the test genuinely cannot continue.
• Compare structs with cmp.Diff, not hand-written field-by-field checks. [Convention]

Documentation

• Every exported name has a doc comment starting with the name itself, written as a complete sentence.
• The package comment sits immediately above package x, with no blank line.

Workflows

Writing new Go code

1. Check go.mod for the language version — it gates loop semantics, generics, and stdlib availability (references/modern-go.md).
2. Read a neighboring file first. Adopt its naming, error style, and test style.
3. Write the smallest thing that works. Concrete types over interfaces; functions over types; a struct over a framework.
4. Design the zero value to be usable, or provide exactly one constructor.
5. Handle every error at the point you get it. Add context that the caller doesn't already have.
6. gofmt → go build ./... → go vet ./... → go test ./... → project's golangci-lint.

Designing an exported API

Load references/api-design.md. The checklist:

• Can a caller misuse this without the compiler stopping them? Tighten the types.
• Is every exported symbol necessary? Unexport what you can — you can always export later, never the reverse.
• Does it take an interface it doesn't need? Take the narrowest thing that works.
• Does it return an interface where a concrete type would tell the caller more? Usually return the concrete type.
• Is the zero value meaningful, or does it panic?
• Does it accept ctx first, return error last?
• Is it safe for concurrent use, and does the doc say so either way?

Reviewing Go

Load references/code-review.md. In order of what matters:

1. Correctness — races, ignored errors, nil derefs, goroutine leaks, resource leaks, loop/slice aliasing.
2. API surface — is the exported shape something you can live with for years?
3. Clarity — will a new reader follow this?
4. Tests — do they test behavior, and do they fail usefully?
5. Style — last, and only what the linter didn't catch.

Say the tier out loud: "blocking: this leaks a goroutine" vs "nit, non-blocking: I'd name this n." Don't dress preferences as rules.

Linting

Always prefer the project's own configuration; never substitute your own.

golangci-lint config path              # what config is actually in effect
golangci-lint run ./...                # full run
golangci-lint run --new-from-rev=HEAD~ # only what this change introduced
golangci-lint fmt                      # apply configured formatters

If the project has no config, run the default linter set and report findings — do not add a .golangci.yml unless asked. Details and failure modes: references/linting.md.

What not to do

• Don't create a .golangci.yml, change lint settings, or add //nolint directives to make a run pass. Fix the code or report the finding.
• Don't refactor beyond the task to satisfy a style preference.
• Don't add an interface, a factory, or a layer of indirection "for testability" before there is a second implementation or a real external dependency.
• Don't reach for a framework where a struct and a function will do.
• Don't quote this skill as authority for a [Judgment] call.