Go conventions

---
name: golang-style-9f91709c4012
description:
  Go conventions specific to this author. Use before writing or editing any Go
  (.go) file.
---

# Go conventions

Where this author deviates from, or tightens, idiomatic Go defaults.

## Errors and control flow

- Structure functions so the happy path flows straight down: handle each error
  and return early, then continue with the main logic. Main logic never nests
  inside an `if err == nil` branch.
- Only wrap errors with `%w` if the underlying error should be
  exposed.
- Define expected error conditions as package-level sentinel errors
  (`var ErrNotFound = errors.New("not found")`) and check them with
  `errors.Is`, not `==` or string matching.

## Go version

Your idea of "current Go" is frozen at your training cutoff and is usually out
of sync with the project in both directions. Before writing code, read the `go`
directive in `go.mod` and check `go version`, and target the lower of the two.

That drift cuts both ways:

- Newer than you know: a helper you are about to hand-roll may already exist in
  `slices`, `maps`, `cmp`, `testing`, or a package you have never heard of.
- Older than you assume: a feature you treat as ordinary may postdate the `go`
  directive and simply not build.

`go doc <pkg>` answers both, but only for the toolchain installed here. To ask
about the version the module actually targets, use the pkg.go.dev API — no auth,
GET only ([announcement](https://go.dev/blog/pkgsite-api), spec at
`https://pkg.go.dev/v1beta/openapi.yaml`):

```sh
# Which symbols does a stdlib package have at a specific Go version?
curl -s "https://pkg.go.dev/v1beta/symbols/slices?version=v1.21.0"

# Current Go release, and any release candidate in flight.
curl -s "https://pkg.go.dev/v1beta/versions/std"

# Third-party: latest version, and the symbols it declares.
curl -s "https://pkg.go.dev/v1beta/module/github.com/google/go-cmp"
curl -s "https://pkg.go.dev/v1beta/symbols/github.com/google/go-cmp/cmp"
```

Release notes are not in the API — fetch https://go.dev/doc/go1.N for a
release's changes, or https://go.dev/doc/devel/release for the index.

## Formatting

- Maximum line length 120 characters. Break long signatures and `fmt.Errorf`
  calls one argument per line.
- Indent with tabs rendered 2 wide.
- Organize imports with `gci`.
- End documentation comments with a period sign.

## Comments

Every comment ends with a period, including inline ones inside a function body.

## Naming

Never shadow a predeclared identifier with a variable or parameter name — not
`new`, `len`, `make`, `copy`, `max`, `min`, `clear`, `any`, `error`, `string`,
or any other builtin function, constant, or type. Pick a descriptive name
instead: `length` over `len`, `dataCopy` over `copy`.

## Sage

If the project has a `.sage` folder (Sage is used), run tasks through the
Sage-generated Makefiles rather than invoking `go` directly.