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.

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

func TestStreamingMemory(t *testing.T) {
    // 1. Create large input (1M entries in t.TempDir())
    // 2. Measure baseline:
    runtime.GC()
    var before runtime.MemStats
    runtime.ReadMemStats(&before)
    // 3. Run the streaming operation
    // 4. Measure after:
    runtime.GC()
    var after runtime.MemStats
    runtime.ReadMemStats(&after)
    // 5. Assert (guard unsigned underflow):
    var growth uint64
    if after.HeapInuse > before.HeapInuse {
        growth = after.HeapInuse - before.HeapInuse
    }
    So(growth, ShouldBeLessThan, 20*1024*1024)
}

Architecture

• cmd/*.go: CLI-only (flag parsing, wiring). No business logic.
• New public packages for new functionality, fully tested via TDD.
• internal/ for shared helpers, mocks, generic utilities.
• main_test.go for integration tests (no mocks, real end-to-end).
• Put genuinely shared internal helpers, mocks, and utilities in internal/. Follow implementation-principles for reuse and abstraction decisions.

Commands

# Tests
CGO_ENABLED=1 go test -tags netgo --count 1 ./<path> -v -run <TestFunc>

# Fuzz exploration (bounded; without -fuzz only the seed corpus runs)
go test ./<path> -fuzz <FuzzFunc> -fuzztime 60s

# Linter (check + autofix)
golangci-lint run --fix

# Clean ordering
cleanorder -min-diff <file>