golang

Go conventions

Standard idiomatic Go applies. These are the rules that differ or that agents keep breaking.

Code

• Never use else, in tests too. Return early, continue, break, or use a switch.
• Comments explain a why the code cannot express: a hidden constraint, a workaround, a surprising invariant. No doc comments that restate a name or signature, exported symbols included.
• Use named fields in every struct literal, never positional ones: fixing fieldalignment findings reorders struct fields.
• Keep lines under 180 characters (lll).
• When a standard library package collides with an existing import, alias it lib<name>, for example libtime.
• Start error strings lowercase, without trailing punctuation.
• Ask before adding a dependency.

Tests

• Assert with testify (assert, require).

• Write table-driven tests: one behavior is one test function with a table. Per-case fixtures, mock returns, and expected errors are table fields, not reasons for a new function. Extend an existing table instead of adding a function. Split when the API under test or the setup and assertion flow differs, and for no other reason.

• Test behavior, not the patch. Name the behavior a test proves, then ask:

  1. Could the original bug still occur while this test passes?
  2. Could a correct refactor make it fail?

  If either answer is yes, redesign or drop the test. Never assert on source text, embedded scripts, or statement order; assert on text when the emitted text is itself the contract (generated shell code, escaping, serialization). When the behavior cannot be exercised, say so instead of adding a proxy test.

• A test that mutates package-level state saves the original value and restores it with t.Cleanup, never a hardcoded value.

Before committing

Run from the module root and fix every finding:

modernize -fix ./...
fieldalignment ./...
golangci-lint run

• Never run fieldalignment -fix: it drops the comments of the fields it reorders. Reorder by hand.
• Commit the modernize rewrites with the change that triggered them.
• After touching a _windows.go, _unix.go, _darwin.go, _linux.go, or //go:build file, also run go build ./..., golangci-lint run, modernize ./..., and fieldalignment ./... with GOOS set to another platform. The host toolchain skips other platforms' files, so their errors otherwise surface in CI.
• dupl on near-identical tests: merge them into one table. Reserve //nolint:dupl, with a reason, for tests that must stay separate. goconst: extract a string literal used three or more times into a constant.