Programming Go

Overview

Write explicit Go with small packages, inspectable errors, and bounded concurrency. Research baseline: stable Go 1.27, checked 2026-09-05. Read go.mod, go.work, toolchain directives, build tags, and CI before introducing newer APIs. Use a supported toolchain, but preserve the module's language compatibility unless an upgrade is requested. Recheck official releases when updating this guidance.

Mental model

Keep control flow and ownership visible. Ordinary functions, structs, and explicit dependency wiring solve most problems. Add an interface, generic abstraction, goroutine, or dependency when it removes a concrete coupling or limitation; don't create infrastructure for hypothetical reuse.

Recent features and compatibility

Go 1.27 JSON v2 rejects duplicate object names and invalid UTF-8 by default. Migration changes wire behavior; inspect the documented differences and test existing payloads. The original encoding/json API remains supported. SIMD packages are still experimental; do not treat them as ordinary stable APIs.

Packages, types, and interfaces

• Keep a package cohesive and its exported surface small. internal/ limits imports to the subtree rooted at its parent directory; it does not mean strictly “same module.” Preserve the existing layout when it serves the task.
• Define a small interface at the consumer when substitution is needed; don't export an interface for every concrete implementation. Return concrete values unless hiding representation is part of the API.
• Use generics when the same algorithm works across types. sync.Pool is not sync.Pool[T]; verify signatures instead of inventing typed variants.
• Prefer useful zero values where possible; use constructors for required invariants. A typed nil pointer inside an interface is a non-nil interface: return an explicit nil on success for error results.
• Treat slices as views over possibly shared storage. Copy before retaining data that the caller may mutate or reuse. Do not copy mutexes, wait groups, or other synchronization values after use.

Errors and boundaries

• Return errors with operation context; use %w when callers should inspect the cause. Check with errors.Is or errors.As, not error-string matching.
• Choose exported sentinel or typed errors only for recovery decisions callers need. Wrapping exposes a cause as part of your API; don't expose implementation errors accidentally.
• Handle or return failures. Log where the request/job is finally handled, avoiding duplicate logs at every layer. Don't turn invalid configuration, malformed input, or failed I/O into successful zero values.
• Close response bodies and files promptly; check write and close errors where they affect durability. Put per-item cleanup in a helper instead of accumulating loop-scoped defer calls until a long function exits.
• Set HTTP timeouts and body limits appropriate to the operation; pass request contexts through network and database calls. Reuse clients and transports.

Concurrency and lifecycle

• Every goroutine needs an owner, completion/error handling, and a way to finish. A WaitGroup waits; it does not cancel work. Bound parallel work and queues.
• Pass context.Context explicitly as the first parameter for operations with cancellation/deadlines. Don't store request contexts in long-lived structs; call returned cancellation functions to release resources.
• Choose a mutex for simple shared state and channels for coordination or ownership transfer. The sending owner closes a channel after its final send; multiple producers need coordinated closure.
• Use errgroup when coordinated work needs error propagation and cancellation. Its context only helps if blocking operations observe cancellation.

Example

Preserve parse errors and reject values outside the domain:

func parseWorkers(raw string) (int, error) {
	n, err := strconv.Atoi(raw)
	if err != nil {
		return 0, fmt.Errorf("parse worker count: %w", err)
	}
	if n < 1 {
		return 0, fmt.Errorf("worker count must be positive")
	}
	return n, nil
}

This function uses the standard fmt and strconv packages.

Checklist

• Language features and standard-library symbols match the module's declared version.
• Errors, nil interfaces, shared slices, cleanup, and cancellation preserve the contract.
• New concurrency has bounded work and a defined shutdown path.
• When authorized, use project formatting, vet, focused tests, and race tests on supported targets. Exercise invalid inputs and concurrent shutdown; report skipped checks.

References

• Release history, Go 1.27, and Go 1.25.
• Language specification and Go code review guidance.
• Context lifecycle, synchronization contracts, and JSON v2.