go-conventions

Files (2)

• SKILL.md
• openai.yaml · agents/

SKILL.md (first lines)

# Go Conventions

Single source of truth for Go code standards. Other skills reference this.

## Copyright Boilerplate

All new source files must start with:

```
/*******************************************************************************
 * Copyright (c) 2026 Genome Research Ltd.
 *
 * Author: Sendu Bala <sb10@sanger.ac.uk>
 *
 * Permission is hereby granted, free of charge, to any person obtaining
 * a copy of this software and associated documentation files (the
 * "Software"), to deal in the Software without restriction, including
 * without limitation the rights to use, copy, modify, merge, publish,
 * distribute, sublicense, and/or sell copies of the Software, and to
 * permit persons to whom the Software is furnished to do so, subject to
 * the following conditions:
 *
 * The above copyright notice and this permission notice shall be included
 * in all copies or substantial portions of the Software.
 *
 * THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND,
 * EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF
 * MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT.
 * IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY
 * CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT,
 * TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE
 * SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.
 ******************************************************************************/
```

## Code Quality

### Modern Go (1.25+)

- Range over integers: `for i := range n` (no C-style loops in new code).
- `log/slog` over `log` or `fmt.Println` for operational output.
- `fmt.Errorf` with `%w`; sentinel errors as package-level `var` with
  `errors.New`; `errors.Is`, or `errors.AsType[T]` rather than `errors.As`
  with a target variable.
- `time` unit constants, not raw nanosecond counts; `for b.Loop()` in
  benchmarks; `defer` for a function's final cleanup step.
- `slices`/`maps` packages instead of hand-written loops.
- Named return values only when they genuinely aid readability.
- Goroutines must have clear exit paths; use `context.Context` for cancellation.

### Style

- Functions ~30 lines max (excluding error handling), but don't scatter logic
  across too many tiny helpers.
- Early returns/guard clauses over nested if/else.
- Doc comments on all exports.
- One responsibility per file; filenames describe the responsibility.
- Import grouping: stdlib | third-party | project (blank-line separated).

### Testing (GoConvey)

- Framework: `github.com/smartystreets/goconvey/convey`.
- `So(actual, ShouldEqual, expected)` assertions - never bare `if` checks.
- `t.TempDir()` for filesystem ops.
- Each `Convey` block independent; no shared mutable state.
- Never put `So()` in loops >20 iterations; count and assert final count.
- Use the matching assertion (`ShouldWrap`, `ShouldHaveLength`, ...), not
  `So(cond, ShouldBeTrue)`.
- Undo state changes (permissions, env, globals) with `Reset`, registered
  before the change; a failing `So` skips any later `defer`. Pass cleanup
  functions directly: `Reset(h.Cleanup)`.
- Never block on a bare channel receive; `select` with a timeout so a missed
  signal fails the test instead of hanging it.
- Follow **testing-principles** for test intent; this section covers GoConvey
  mechanics.
- Every spec.md acceptance test MUST have a corresponding GoConvey test. No
  stubs, no hardcoded results, no swallowed failures, no build-tag exclusions.

### Fuzzing

Reach for a fuzz target when a claim must hold across a whole input domain
rather than at the worked examples a spec names: overflow and rounding safety
over a numeric range, a round-trip through an encoder, a parser that must
never panic. **testing-principles** decides when one is owed and what property
to assert; this section covers the Go mechanics.

```go
func FuzzScale(f *testing.F) {
    f.Add(int64(0), int64(1), int64(1))
    f.Add(int64(math.MaxInt64), int64(2), int64(2))

    f.Fuzz(func(t *testing.T, value, num, den int64) {
        if den == 0 {
            return // the documented panic has its own Convey test
        }

        got, want := mathx.Scale(value, num, den), slowExactScale(value, num, den)
        if got != want {
            t.Fatalf("Scale(%d,%d,%d) = %d, want %d", value, num, den, got, want)
        }
    })
}
```

- Assert with plain `if` and `t.Fatalf` inside `f.Fuzz`, not `So()`. The body
  runs millions of times, so the loop rule above applies.
- `f.Add` every boundary, zero and sign combination. Without `-fuzz`, `go
  test` runs the seed corpus and nothing else, so the seeds are what CI
  executes and they must stand on their own as a table test.
- Assert a property, never a second copy of the implementation. A target that
  recomputes the function the same way proves only self-consistency.
- Constrain the domain in the target and leave documented panics and sentinel
  errors to their Convey tests.
- Commit the crasher. A failure writes its input to
  `<pkg>/testdata/fuzz/FuzzX/<hash>`, beside the package and not at the module
  root. That file is the regression test: it then runs under plain `go test`,
  so `git add` it with the fix.

### Memory-Bounded Test Pattern

From wtsi-hgi/agentskills, MIT.

More from wtsi-hgi/agentskills