Go Engineering Excellence

This skill provides comprehensive Go engineering guidelines synthesized from authoritative sources including the Go team, Google, Uber, and experienced Go practitioners. Use this when writing or reviewing Go code for production systems.

Core Philosophy

Design Principles (Google Go Style)

• Clarity - Code's purpose and rationale must be clear to readers

• Simplicity - Accomplish goals in the simplest way possible

• Concision - High signal-to-noise ratio

• Maintainability - Easy for future programmers to modify correctly

• Consistency - Consistent with the broader codebase

Make Dependencies Explicit

• Never use package-level global state

• Avoid func init()

• it exists only to modify global state

• Pass dependencies as constructor parameters, not globals

• All configuration should flow through explicit parameters

Project Structure

Repository Layout

github.com/org/project/ cmd/ server/ main.go cli/ main.go pkg/ domain/ domain.go domain_test.go api/ api.go api_test.go Dockerfile go.mod go.sum

Guidelines:

• Library code goes under pkg/ subdirectory

• Binaries go under cmd/ subdirectory

• Always use fully-qualified import paths (never relative imports)

• Package names should be lowercase, single-word, domain-oriented

• Avoid package names like util , common , helpers , models

Naming Conventions

General Rules

• Use MixedCaps or mixedCaps , never snake_case

• Keep names proportional to scope size

• Short names (1-2 letters) acceptable for small scopes

• Longer, descriptive names for package/file scope

Specific Conventions

Constants:

// Good const MaxPacketSize = 512 const ( ExecuteBit = 1 << iota WriteBit ReadBit )

// Bad - don't use const MAX_PACKET_SIZE = 512 // Wrong const kMaxBufferSize = 1024 // Wrong

Functions/Methods:

• Don't include type names: user.ID() not user.GetUserID()

• No Get prefix: Owner() not GetOwner()

• Avoid repetition with package: buf.Reader not buf.BufReader

Receivers:

• Short (1-2 letters), abbreviation of type name

• Consistent across all methods: always u for User , never mix u and user

Initialisms:

// Good var userID string // ID not Id var xmlAPI string // API not Api var urlPony string // URL not Url

// Bad var userId string var xmlApi string

Variables

Scope-based naming:

• Small scope (1-7 lines): c , i , n

• Medium scope (8-15 lines): count , index , node

• Large scope (15-25 lines): userCount , requestIndex

• Very large scope (>25 lines): Descriptive multi-word names

Common conventions:

• r for io.Reader or *http.Request

• w for io.Writer or http.ResponseWriter

• ctx for context.Context

Code Organization

Struct Initialization

// Good - use field names, omit zero values cfg := Config{ Timeout: 5 * time.Second, MaxConn: 100, }

// Good - inline for immediate use client := New(Config{ Timeout: 5 * time.Second, MaxConn: 100, })

// Bad - piecemeal construction cfg := Config{} cfg.Timeout = 5 * time.Second cfg.MaxConn = 100

Constructor Patterns

// Good - explicit dependencies func NewService( logger *log.Logger, db *sql.DB, cache Cache, ) *Service { // Provide sensible defaults if logger == nil { logger = log.New(ioutil.Discard, "", 0) }

return &Service{
    logger: logger,
    db:     db,
    cache:  cache,
}

}

// Bad - hidden dependencies var globalLogger *log.Logger

func NewService(db *sql.DB) *Service { return &Service{ logger: globalLogger, // Hidden dependency! db: db, } }

Interface Design

// Good - small, focused interfaces type Reader interface { Read(p []byte) (n int, err error) }

type Closer interface { Close() error }

type ReadCloser interface { Reader Closer }

// Good - accept interfaces, return concrete types func ProcessData(r io.Reader) (*Result, error) { // ... }

// Bad - large, unfocused interfaces type DataStore interface { Get(key string) (interface{}, error) Set(key string, value interface{}) error Delete(key string) error List() ([]interface{}, error) Count() int Clear() error // ... many more methods }

Error Handling

Error Types

// Static errors - use errors.New var ErrNotFound = errors.New("not found") var ErrInvalidInput = errors.New("invalid input")

// Dynamic errors - use fmt.Errorf with %w func Open(name string) error { return fmt.Errorf("open %s: %w", name, ErrNotFound) }

// Custom error types for additional context type ValidationError struct { Field string Value interface{} }

func (e *ValidationError) Error() string { return fmt.Sprintf("invalid %s: %v", e.Field, e.Value) }

Error Handling Patterns

// Good - handle errors once func process() error { data, err := fetch() if err != nil { return fmt.Errorf("fetch data: %w", err) } return save(data) }

// Bad - log and return func process() error { data, err := fetch() if err != nil { log.Printf("error: %v", err) // Don't do this! return err // AND this! } return save(data) }

// Good - add context when wrapping return fmt.Errorf("process user %s: %w", userID, err)

// Bad - generic wrappers return fmt.Errorf("failed to process: %w", err)

Error String Conventions

// Good - lowercase, no punctuation errors.New("something went wrong") fmt.Errorf("connection failed")

// Bad errors.New("Something went wrong.") // Capital and period fmt.Errorf("Connection Failed!") // Wrong capitalization

Concurrency

Goroutine Lifecycle

// Good - explicit lifecycle management type Server struct { wg sync.WaitGroup ctx context.Context cancel context.CancelFunc }

func (s *Server) Start() { s.ctx, s.cancel = context.WithCancel(context.Background())

s.wg.Add(1)
go func() {
    defer s.wg.Done()
    s.worker(s.ctx)
}()

}

func (s *Server) Stop() { s.cancel() s.wg.Wait() }

// Bad - fire and forget func process() { go doSomething() // How does it stop? }

Channel Patterns

Channels should be unbuffered or size 1:

// Good done := make(chan struct{}) // Unbuffered results := make(chan Result, 1) // Size 1

// Questionable - needs strong justification queue := make(chan Task, 100)

Futures/Async-Await:

// Future pattern future := make(chan Result, 1) go func() { future <- compute() }() result := <-future

// Scatter-gather results := make(chan Result, 10) for i := 0; i < cap(results); i++ { go func() { results <- process() }() }

for i := 0; i < cap(results); i++ { result := <-results // handle result }

Mutexes

// Good - zero-value mutex is valid type Counter struct { mu sync.Mutex count int }

// Bad - unnecessary pointer type Counter struct { mu *sync.Mutex count int }

// Bad - embedded mutex exposes Lock/Unlock type Counter struct { sync.Mutex count int }

Context Usage

When to Use Context

// Good - context as first parameter func ProcessRequest(ctx context.Context, req *Request) error { // ... }

// Good - pass through call chain func (s *Service) Handle(ctx context.Context) error { return s.process(ctx) }

// Bad - context in struct type Handler struct { ctx context.Context // Don't do this }

// Exception - methods matching standard library func (c *Client) Do(req *http.Request) (*http.Response, error) { // OK - matching http.Client.Do signature }

Context Values

// Use context for request-scoped data type contextKey string

const requestIDKey contextKey = "request-id"

func WithRequestID(ctx context.Context, id string) context.Context { return context.WithValue(ctx, requestIDKey, id) }

func RequestID(ctx context.Context) string { if id, ok := ctx.Value(requestIDKey).(string); ok { return id } return "" }

// Don't use context to pass optional parameters // Don't create custom context types

Configuration

Use Flags

// Good - flags in main func main() { var ( addr = flag.String("addr", ":8080", "listen address") timeout = flag.Duration("timeout", 30*time.Second, "request timeout") debug = flag.Bool("debug", false, "enable debug mode") ) flag.Parse()

cfg := Config{
    Addr:    *addr,
    Timeout: *timeout,
    Debug:   *debug,
}

// Use cfg...

}

// Bad - configuration via globals var Config struct { Addr string }

func init() { Config.Addr = os.Getenv("ADDR") // Don't do this }

Config Objects

// Good - zero values are useful type Config struct { Logger *log.Logger // nil = discard Timeout time.Duration // 0 = no timeout Retries int // 0 = no retries }

func New(cfg Config) *Service { if cfg.Logger == nil { cfg.Logger = log.New(ioutil.Discard, "", 0) } if cfg.Timeout == 0 { cfg.Timeout = 30 * time.Second } // ... }

Testing

ALWAYS use the testify require library for test assertions. Try avoid require.ErrorContains and use sentinel errors in the code instead, and require.Error{Is,As} in the test.

Table-Driven Tests

func TestProcess(t *testing.T) { testCases := []struct { name string input string expectedResult string expectedErr bool }{ { name: "valid input", input: "test", expectedResult: "TEST", }, { name: "empty input", input: "", expectedErr: true, }, }

for _, tc := range testCases {
    t.Run(tc.name, func(t *testing.T) {
        result, err := Process(tc.input)
        require.Equal(t, tc.expectedErr, err != nil)
        require.Equal(t, tc.expectedResult, result)
    })
}

}

Test Helpers

// Good - test helpers using require (preferred over t.Fatal) func mustConnect(t *testing.T, dsn string) *sql.DB { t.Helper() db, err := sql.Open("postgres", dsn) require.NoError(t, err, "failed to connect") return db }

// Good - cleanup with t.Cleanup func TestServer(t *testing.T) { db := mustConnect(t, testDSN) t.Cleanup(func() { db.Close() }) // test code... }

// Good - use t.TempDir() for automatic cleanup func createTestFile(t *testing.T, content string) string { t.Helper() tmpDir := t.TempDir() // Automatically cleaned up path := tmpDir + "/test.txt" err := os.WriteFile(path, []byte(content), 0644) require.NoError(t, err, "failed to write test file") return path }

// Bad - using t.Fatal directly func mustConnect(t *testing.T, dsn string) *sql.DB { t.Helper() db, err := sql.Open("postgres", dsn) if err != nil { t.Fatalf("failed to connect: %v", err) // Don't use t.Fatal - use require } return db }

Test Helper Guidelines:

• Always call t.Helper() at the start of test helpers

• Use require assertions instead of t.Fatal for consistency

• Use t.TempDir() for temporary directories (automatic cleanup)

• Use t.Cleanup() for resource cleanup

• Keep helpers focused and reusable

Mocking

// Good - small interfaces for easy mocking type Store interface { Get(id string) (*User, error) }

type mockStore struct { users map[string]*User }

func (m *mockStore) Get(id string) (*User, error) { u, ok := m.users[id] if !ok { return nil, ErrNotFound } return u, nil }

// Test code func TestService(t *testing.T) { store := &mockStore{ users: map[string]*User{ "1": {ID: "1", Name: "Alice"}, }, } svc := NewService(store) // test svc... }

Performance

Prefer strconv over fmt

// Good - fast i := 42 s := strconv.Itoa(i)

// Bad - slow s := fmt.Sprintf("%d", i)

Specify Capacity

// Good users := make([]User, 0, len(ids)) for _, id := range ids { users = append(users, User{ID: id}) }

cache := make(map[string]*Value, 1000)

// Also good - when size is known exactly results := make([]Result, len(inputs)) for i, input := range inputs { results[i] = process(input) }

Avoid String-to-Byte Conversions

// Good - reuse bytes var buf bytes.Buffer for _, s := range strings { buf.WriteString(s) } result := buf.Bytes()

// Bad - repeated conversions var result []byte for _, s := range strings { result = append(result, []byte(s)...) }

Common Patterns

Defer for Cleanup

// Good func process(filename string) error { f, err := os.Open(filename) if err != nil { return err } defer f.Close()

// Process file...
return nil

}

// Also good - with error check defer func() { if err := f.Close(); err != nil { log.Printf("failed to close: %v", err) } }()

Copying Slices and Maps

// Good - defensive copying when receiving func (d *Data) SetItems(items []Item) { d.items = make([]Item, len(items)) copy(d.items, items) }

// Good - defensive copying when returning func (d *Data) Items() []Item { result := make([]Item, len(d.items)) copy(result, d.items) return result }

Type Assertions

// Good - check success if val, ok := x.(string); ok { // use val }

// Also good - type switch switch v := x.(type) { case string: // use v as string case int: // use v as int default: // handle unknown type }

// Bad - will panic on wrong type val := x.(string)

Observability

Structured Logging

// Good - structured fields logger.Info("processing request", "user_id", userID, "duration_ms", duration.Milliseconds(), "status", status, )

// Bad - string formatting log.Printf("processing request user=%s duration=%v status=%d", userID, duration, status)

Metrics

// Good - instrument at component boundaries type Server struct { requests prometheus.Counter errors prometheus.Counter duration prometheus.Histogram }

func (s *Server) Handle(w http.ResponseWriter, r *http.Request) { start := time.Now() defer func() { s.requests.Inc() s.duration.Observe(time.Since(start).Seconds()) }()

// Handle request...

}

Anti-Patterns to Avoid

Don't Panic

// Bad - panic in library code func process(data []byte) { if len(data) == 0 { panic("empty data") // Don't! } }

// Good - return error func process(data []byte) error { if len(data) == 0 { return errors.New("empty data") } return nil }

// OK - panic in main for initialization func main() { db, err := sql.Open("postgres", dsn) if err != nil { panic(err) // OK in main } }

Avoid Naked Returns

// Bad func compute(x int) (result int) { result = x * 2 return // Naked return - unclear }

// Good func compute(x int) int { result := x * 2 return result }

Don't Use Import Dot

// Bad import . "fmt"

func main() { Println("hello") // Unclear where Println comes from }

// Good import "fmt"

func main() { fmt.Println("hello") // Clear }

Documentation

Package Comments

// Package auth provides authentication and authorization utilities. // // It supports multiple authentication backends including OAuth2, // JWT tokens, and API keys. package auth

Function Comments

// Process validates and transforms the input data. // It returns an error if validation fails. // // Example usage: // // result, err := Process(data) // if err != nil { // log.Fatal(err) // } func Process(data []byte) (*Result, error) { // ... }

Guard Clauses and Early Returns

Use guard clauses (early returns) to reduce nesting and improve readability.

// Good - guard clauses with early returns func process(data []byte) error { if len(data) == 0 { return errors.New("empty data") }

if !isValid(data) { return errors.New("invalid data") }

// Main logic at base indentation level result := transform(data) return save(result) }

// Bad - nested conditionals func process(data []byte) error { if len(data) > 0 { if isValid(data) { result := transform(data) return save(result) } else { return errors.New("invalid data") } } else { return errors.New("empty data") } }

In loops - use early continue:

// Good - early continue for _, item := range items { if item == nil { continue } if !item.IsValid() { continue }

// Process valid item process(item) }

// Bad - nested ifs for _, item := range items { if item != nil { if item.IsValid() { process(item) } } }

Benefits:

• Keeps happy path at minimal indentation

• Reduces cognitive load

• Makes error conditions obvious

• Easier to read top-to-bottom

This is commonly called the "happy path" or "guard clause" pattern in Go.

Tooling

Language Server

• ALWAYS use the gopls MCP server (mcp-gopls ) for all Go development

• Leverage gopls capabilities: diagnostics, symbol search, file context, package API, references

• Use go_workspace to understand workspace structure

• Use go_diagnostics to check for build and analysis errors after code changes

• Use go_file_context to understand a file's dependencies within its package

• Use go_symbol_references to find all references before modifying symbol definitions

Code Formatting

• ALWAYS run gofmt after making any code changes - this is non-negotiable

• Use goimports as an alternative to gofmt that also manages imports

• Format before running any other checks

Linting with golangci-lint

ALWAYS run golangci-lint after making code changes before considering the work complete.

When to run:

• After implementing new features or bug fixes

• Before creating commits

• After refactoring

• During code review

How to run:

Run on entire project

golangci-lint run

Run on specific directory

golangci-lint run ./pkg/...

Run on specific files

golangci-lint run path/to/file.go

Handling linter output:

• Fix all errors - these are non-negotiable

• Fix warnings unless there's a strong technical reason not to (document why)

• Review info messages and apply fixes when they improve code quality

• Never ignore linter feedback without understanding what it's flagging

Common linters enforced:

• errcheck

• Unchecked errors

• gosimple

• Simplification opportunities

• govet

• Suspicious constructs

• ineffassign

• Ineffectual assignments

• staticcheck

• Advanced static analysis

• unused

• Unused code

• gofmt

• Formatting issues

• And many more...

Complete Pre-commit Workflow

Run these commands in order before committing:

1. Format code

go fmt ./...

2. Run linter

golangci-lint run

3. Run tests

go test -v ./... -tags=sqlite -failfast

4. Check for build errors (if applicable)

go build ./...

All checks must pass before code is ready for review.

Additional Resources

• Effective Go

• Go Code Review Comments

• Google Go Style Guide

• Uber Go Style Guide

• Go Proverbs

Remember: These guidelines are not absolute rules. Use judgment and adapt them to your specific context, but always favor explicitness, simplicity, and maintainability.