Go Engineering

Design Guidelines

• Keep things simple.
  • Prefer stateless, pure functions over stateful structs with methods if no state is needed to solve the problem.
  • Prefer synchronous code to concurrent code, an obvious concurrency pattern applies.
  • Prefer simple APIs and small interfaces.
  • Make the zero value useful:

    bytes.Buffer

    and

    sync.Mutex

    work without init. When zero values compose, there's less API.
  • Avoid external dependencies. A little copying is better than a little dependency.
• Clear is better than clever. Maintainability and readibility are important.
• Don't just check errors, handle them gracefully.
• Design the architecture, name the components, document the details: Good names carry the weight of expressing your design. If names are good, the design is clear on the page.
• Reduce nesting by using guard clauses.
  • Invert conditions for early return
  • In loops, use early

    continue

    for invalid items instead of nesting
  • Max 2-3 nesting levels
  • Extract helpers for long methods

Code Style

• Avoid stuttering:

  http.Client

  not

  http.HTTPClient

• Getters:

  Foo()

  not

  GetFoo()

• Receiver: short (1-2 chars), consistent across type methods

• Must

  prefix for panicking functions
• Enums: use

  iota + 1

  to start at one, distinguishing intentional values from zero default

Error Handling

• Errors are values. Design APIs around that.
• Wrap with context:

  fmt.Errorf("get config %s: %w", name, err)

• Sentinel errors:

  var ErrNotFound = errors.New("not found")

• Check with

  errors.Is(err, ErrNotFound)

  or

  errors.As(err, &target)

  , or use generic

  errors.AsType[T]

  (Go 1.26+)
• Static errors: prefer

  errors.New

  over

  fmt.Errorf

  without formatting
• Join multiple errors:

  err := errors.Join(err1, err2, err3)

  (Go 1.20+)
• Error strings: lowercase, no punctuation
• Avoid "failed to" prefixes - they accumulate through the stack (

  "connect: %w"

  not

  "failed to connect: %w"

  )
• CRITICAL: Always check errors immediately before using returned values (Go 1.25 fixed compiler bug that could delay nil checks)

Error Strategy (Opaque Errors First)

1. Opaque errors (preferred): return and wrap errors without exposing type or value. Callers only check

   err != nil

   .
2. Sentinel errors (

   var ErrNotFound = errors.New(...)

   ): use sparingly for expected conditions callers must distinguish. They become public API.
3. Error types (

   type NotFoundError struct{...}

   ): use when callers need structured context. Also public API — avoid when opaque or sentinel suffices.

Assert Behavior, Not Type

errors.Is

errors.As

type temporary interface {
    Temporary() bool
}

func IsTemporary(err error) bool {
    te, ok := err.(temporary)
    return ok && te.Temporary()
}

Handle Errors Once

// Bad: logs AND returns
if err != nil {
    log.Printf("connect failed: %v", err)
    return fmt.Errorf("connect: %w", err)
}

// Good: wrap and return; let the top-level caller log
if err != nil {
    return fmt.Errorf("connect to %s: %w", addr, err)
}

Context with Cause (Go 1.21+)

ctx, cancel := context.WithCancelCause(parent)
cancel(fmt.Errorf("shutdown: %w", reason))

// Later retrieve the cause
if cause := context.Cause(ctx); cause != nil {
    log.Printf("context cancelled: %v", cause)
}

Generics

• Type parameters:

  func Min[T cmp.Ordered] (a, b T) T

• Use

  comparable

  for map keys,

  cmp.Ordered

  for sortable types
• Custom constraints:

  type Number interface { ~int | ~int64 | ~float64 }

• Generic type alias (Go 1.24+):

  type Set[T comparable] = map[T]struct{}

• Self-referential constraints (Go 1.26+):

  type Adder[A Adder[A]] interface { Add(A) A }

• Prefer concrete types when generics add no value
• Use

  any

  sparingly; prefer specific constraints

Built-in Functions

• min(a, b, c)

  and

  max(a, b, c)

  - compute smallest/largest values (Go 1.21+)

• clear(m)

  - delete all map entries;

  clear(s)

  - zero all slice elements (Go 1.21+)

• new(expr)

  - allocate and initialize with value (Go 1.26+):

  ptr := new(computeValue())

Testing

Table-Driven Tests

func TestFoo(t *testing.T) {
    tests := []struct {
        name    string
        input   string
        want    string
        wantErr error
    }{
        {"EmptyInput", "", "", ErrEmpty},
        {"ValidInput", "hello", "HELLO", nil},
    }
    for _, tc := range tests {
        t.Run(tc.name, func(t *testing.T) {
            t.Parallel()
            got, err := Foo(tc.input)
            if tc.wantErr != nil {
                require.ErrorIs(t, err, tc.wantErr)
                return
            }
            require.NoError(t, err)
            require.Equal(t, tc.want, got)
        })
    }
}

Benchmarks (Go 1.24+)

func BenchmarkFoo(b *testing.B) {
    for b.Loop() {  // Cleaner than for i := 0; i < b.N; i++
        Foo()
    }
}

-count

Assertions

• Use the testify library for conciseness. Use

  require

  for fatal assertions,

  assert

  for non-fatal

• require.ErrorIs

  for sentinel errors (not string matching)

• require.JSONEq

  /

  require.YAMLEq

  for semantic comparison
• Use

  testdata/

  folders for expected values
• Use

  embed.FS

  for test data files

Practices

• t.Helper()

  in helper functions

• t.Cleanup()

  for resource cleanup

• t.Context()

  for test-scoped context (Go 1.24+)

• t.Chdir()

  for temp directory changes (Go 1.24+)

• t.ArtifactDir()

  for test output files (Go 1.26+)

• t.Parallel()

  for independent tests

• -race

  flag always
• Don't test stdlib; test YOUR code
• Bug fix → add regression test first
• Concurrent code needs concurrent tests

Testing Concurrent Code with synctest (Go 1.25+)

testing/synctest

import "testing/synctest"

func TestPeriodicWorker(t *testing.T) {
    synctest.Test(t, func(t *testing.T) {
        var count atomic.Int32
        go func() {
            for {
                time.Sleep(time.Second)
                count.Add(1)
            }
        }()

        // Fake clock advances 5s instantly (no real waiting)
        time.Sleep(5 * time.Second)
        synctest.Wait() // wait for all goroutines to settle
        require.Equal(t, int32(5), count.Load())
    })
}

• synctest.Wait()

  blocks until all bubble goroutines are idle

• time.Sleep

  ,

  time.After

  ,

  time.NewTimer

  ,

  time.NewTicker

  all use the fake clock inside the bubble
• Goroutines spawned inside the bubble belong to it; goroutines outside are unaffected
• Blocking on I/O or syscalls does NOT advance the clock — only channel ops, sleeps, and sync primitives do
• Prefer

  synctest.Test

  over manual

  timeNow

  mocking for new code

Concurrency

Design

• Don't communicate by sharing memory, share memory by communicating
• Channels orchestrate; mutexes serialize
• Use

  errgroup.WithContext

  to launch goroutines that return errors;

  g.Wait()

  returns first error

• sync.WaitGroup.Go()

  (Go 1.25+): cleaner goroutine launching
  go

  var wg sync.WaitGroup
  wg.Go(func() { work() })  // Combines Add(1) + go
  wg.Wait()

• Make goroutine lifetime explicit; document when/why they exit
• Avoid goroutine leaks (blocked on unreachable channels); use goroutine leak profile to detect (

  GOEXPERIMENT=goroutineleakprofile

  , Go 1.26+)
• Use

  context.Context

  for cancellation
• Subscribe to

  context.Done()

  for graceful shutdown
• Prefer synchronous functions; let callers add concurrency if needed

• sync.Mutex

  /

  RWMutex

  for protection; zero value is ready to use

• RWMutex

  when reads >> writes
• Pointer receivers with mutexes (prevent struct copy)
• Keep critical sections small; avoid locks across I/O

• sync.Once

  for one-time initialization; helpers:

  sync.OnceFunc()

  ,

  sync.OnceValue()

  ,

  sync.OnceValues()

  (Go 1.21+)

• atomic

  for primitive counters
• Don't embed mutex (exposes Lock/Unlock); use named field
• Channels:
  • Sender closes, receiver checks
  • Don't close from receiver side
  • Never close with multiple concurrent senders
  • Document buffering rationale
  • Prefer

    select

    with

    context.Done()

    for cancellation

Axioms

• Nil channels are useful in

  select

  to disable a case
• Use

  for range ch

  to receive until closed
• Check closure with

  v, ok := <-ch

Iterators (Go 1.22+)

Range Over Integers (Go 1.22+)

for i := range 10 {
    fmt.Println(i)  // 0..9
}

Range Over Functions (Go 1.23+)

// String iterators
for line := range strings.Lines(s) { }
for part := range strings.SplitSeq(s, sep) { }
for field := range strings.FieldsSeq(s) { }

// Slice iterators
for i, v := range slices.All(items) { }
for v := range slices.Values(items) { }
for v := range slices.Backward(items) { }
for chunk := range slices.Chunk(items, 3) { }

// Map iterators
for k, v := range maps.All(m) { }
for k := range maps.Keys(m) { }
for v := range maps.Values(m) { }

// Collect iterator to slice
keys := slices.Collect(maps.Keys(m))
sorted := slices.Sorted(maps.Keys(m))

// Custom iterator
func (s *Set[T]) All() iter.Seq[T] {
    return func(yield func(T) bool) {
        for v := range s.items {
            if !yield(v) {
                return
            }
        }
    }
}

Interface Design

• Accept interfaces, return concrete types
• Define interfaces at the consumer, not the provider; keep them small (1-2 methods)
• Compile-time interface check:

  var _ http.Handler = (*MyHandler)(nil)

• For single-method dependencies, use function types instead of interfaces
• Don't embed types in exported structs—exposes methods and breaks API compatibility

Slice & Map Patterns

• Pre-allocate when size known:

  make([]User, 0, len(ids))

• Nil vs empty:

  var t []string

  (nil, JSON null) vs

  t := []string{}

  (non-nil, JSON

  []

  )
• Copy at boundaries with

  slices.Clone(items)

  to prevent external mutations
• Prefer

  strings.Cut(s, "/")

  over

  strings.Split

  for prefix/suffix extraction
• Append handles nil:

  var items []Item; items = append(items, newItem)

Common Patterns

Options Pattern

type Option func(*Config)

WithX

Option

...Option

Default Values (Go 1.22+)

cmp.Or(a, b, c)

cmp.Or(cfg.Port, envPort, 8080)

Context Usage

• First parameter:

  func Foo(ctx context.Context, ...)

• Don't store in structs
• Use for cancellation, deadlines, request-scoped values only

HTTP Best Practices

• Use

  http.Server{}

  with explicit

  ReadTimeout

  /

  WriteTimeout

  ; avoid

  http.ListenAndServe

• Always

  defer resp.Body.Close()

  after checking error
• Accept

  *http.Client

  as dependency for testability

HTTP Routing (Go 1.22+)

// Method-based routing with path patterns
mux.HandleFunc("POST /items/create", createHandler)
mux.HandleFunc("GET /items/{id}", getHandler)
mux.HandleFunc("GET /files/{path...}", serveFiles)  // Greedy wildcard

// Extract path values
func getHandler(w http.ResponseWriter, r *http.Request) {
    id := r.PathValue("id")
}

CSRF Protection (Go 1.25+)

import "net/http"

handler := http.CrossOriginProtection(myHandler)
// Rejects non-safe cross-origin requests using Fetch metadata

Directory-Scoped File Access (Go 1.24+)

root, err := os.OpenRoot("/var/data")
if err != nil {
    return err
}
f, err := root.Open("file.txt")  // Can't escape /var/data

Cleanup Functions (Go 1.24+)

runtime.AddCleanup(obj, func() { cleanup() })

SetFinalizer

Structured Logging (log/slog)

• Use

  slog.Info("msg", "key", value, "key2", value2)

  with key-value pairs
• Add persistent attributes:

  logger := slog.With("service", "api")

• JSON output:

  slog.New(slog.NewJSONHandler(os.Stdout, &slog.HandlerOptions{Level: slog.LevelDebug}))

Common Gotchas

• Check errors immediately (Go 1.25 fixed compiler bug): always check

  err != nil

  before using any returned values
  go

  // WRONG: could execute f.Name() before err check in Go 1.21-1.24
  f, err := os.Open("file")
  name := f.Name()
  if err != nil { return }
  
  // CORRECT: check immediately
  f, err := os.Open("file")
  if err != nil { return }
  name := f.Name()

• time.Ticker

  : always call

  Stop()

  to prevent leaks
• Slices hold refs to backing arrays (can retain large memory)

• nil

  interface vs

  nil

  concrete:

  var err error = (*MyError)(nil)

  →

  err != nil

  is true
• Loop variables: each iteration has own copy (Go 1.22+); older versions share
• Timer/Ticker channels: capacity 0 (Go 1.23+); previously capacity 1

• init()

  is an anti-pattern; prefer explicit initialization

Linting (golangci-lint)

# .golangci.yml
linters:
  enable:
    - errcheck      # Unchecked errors
    - govet         # Suspicious constructs
    - staticcheck   # Static analysis
    - unused        # Unused code
    - gosimple      # Simplifications
    - ineffassign   # Ineffectual assignments
    - typecheck     # Type checking
    - gocritic      # Opinionated checks
    - gofumpt       # Stricter gofmt
    - misspell      # Spelling
    - nolintlint    # Malformed //nolint directives
    - wrapcheck     # Errors from external packages wrapped
    - errorlint     # errors.Is/As usage

linters-settings:
  govet:
    enable-all: true
  gocritic:
    enabled-tags: [diagnostic, style, performance]

golangci-lint run              # Lint current module
golangci-lint run --fix        # Auto-fix where possible
golangci-lint run --timeout 5m # Increase timeout for large codebases

Pre-Commit

make help

• make lint

  or

  make check

• make test

• make build

1. go build ./...

2. go test -v -race ./...

3. golangci-lint run

4. go fix ./...

   (Go 1.26+: modernizes code to latest idioms)

5. gofmt -w .

   or

   goimports -w .

6. go mod tidy

Performance

Profile-Guided Optimization (PGO)

# Collect profile
go test -cpuprofile=default.pgo

# PGO automatically enabled if default.pgo exists in main package
go build  # Uses default.pgo

# Typical 2-7% performance improvement

Security

Quick Checklist

• All user input validated server-side
• SQL queries use prepared statements only
• XSS protection via

  html/template

• CSRF tokens on state-changing requests
• File paths validated against traversal (

  os.OpenRoot

  Go 1.24+)

• Passwords hashed with bcrypt/Argon2/PBKDF2

• crypto/rand

  for all tokens/session IDs (

  crypto/rand.Text()

  Go 1.24+)
• Secure cookie flags (HttpOnly, Secure, SameSite)
• Session expiration enforced

• HTTPS/TLS everywhere, TLS 1.2+ only (post-quantum ML-KEM default Go 1.24+)
• HSTS header set

• InsecureSkipVerify = false

• Secrets in environment variables, never in logs/errors
• Generic error messages to users

Detailed Guides

• Input Validation — whitelisting, boundary checks, escaping
• Database Security — prepared statements, parameterized queries
• Authentication — bcrypt, password storage
• Cryptography —

  crypto/rand

  , never

  math/rand

  for security
• Session Management — secure cookies, session lifecycle
• TLS/HTTPS — TLS config, HSTS, post-quantum key exchanges
• CSRF Protection — token generation,

  http.CrossOriginProtection

  (Go 1.25+)
• Secure Error Handling — generic user messages, detailed server logs
• File Security — path traversal prevention,

  os.OpenRoot

• Security Logging — what to log, what never to log
• Access Control
• XSS Prevention

Security Tools

gosec ./...

govulncheck ./...

trivy fs .