Uber Go Style Guide

The Uber Go Style Guide defines the conventions and idiomatic practices used at Uber to ensure codebases remain manageable and productive. It covers more than just formatting (which is handled by gofmt) and includes guidelines on:

• Guidelines: Best practices for pointers, interfaces, mutexes, concurrency, and error handling.
• Performance: Optimization techniques like preferring strconv over fmt and managing container capacity.
• Style: Conventions for naming, grouping declarations, reducing nesting, and initializing structs/maps.
• Patterns: Common architectural patterns like Functional Options and Test Tables.

This guide is based on Effective Go, Go Common Mistakes, and Go Code Review Comments.

To correctly implement background tasks in a package, follow these patterns:

1. Encapsulation: Wrap the goroutine logic within a struct.
2. Controlled Start: Only start the goroutine when the user explicitly calls a constructor like NewWorker().
3. Signaling Stop: Use a channel (e.g., stop) to signal the goroutine to terminate.
4. Waiting for Exit: Use a second channel (e.g., done) or a sync.WaitGroup to ensure the Shutdown method blocks until the goroutine has actually exited.

If the worker manages multiple goroutines, use sync.WaitGroup to coordinate their exit.

In Go, nil is a valid slice of length 0. Follow these rules for slice management:

• Return nil instead of an explicit empty slice []T{} when returning a zero-length slice.
• Check for emptiness using len(s) == 0 rather than checking s == nil.
• Use var to declare empty slices that will be populated via append, as the zero value is immediately usable without make().

// Return nil for empty slices
if x == "" {
  return nil
}

// Check emptiness using len()
func isEmpty(s []string) bool {
  return len(s) == 0
}

// Use var for slices to be appended to
var nums []int
if add1 {
  nums = append(nums, 1)
}

While init() should generally be avoided, it may be preferable or necessary in the following scenarios:

• Complex expressions: When initialization requires logic that cannot be represented as a single variable assignment.
• Pluggable hooks: For implementing registries, such as database/sql dialects or encoding type registries.
• Deterministic precomputation: For optimizations in environments like Google Cloud Functions, where using global variables can allow for object reuse across future invocations.

When designing APIs, avoid long lists of mandatory parameters.

Bad Pattern: Using fixed arguments for optional features. This forces the caller to provide default values or dummy values (like zap.NewNop()) even when they don't want to configure that specific feature.

Good Pattern: Using Functional Options. This allows the caller to provide only the options they care about, while the constructor handles defaults internally.

// BAD: Parameters must always be provided
db.Open(addr, db.DefaultCache, zap.NewNop())

// GOOD: Options are provided only if needed
db.Open(addr)
db.Open(addr, db.WithLogger(log))

Embedding an interface or a pointer type can break the usefulness of a struct's zero value, leading to nil pointer panics when calling embedded methods. To ensure a useful zero value, embed concrete types that are ready to use upon declaration.

Comparison

Bad: Embedding an interface (causes panics)

type Book struct {
    io.ReadWriter
    // other fields
}

var b Book
b.Read(...)  // panic: nil pointer

Good: Embedding a concrete type (safe zero value)

type Book struct {
    bytes.Buffer
    // other fields
}

var b Book
b.Read(...)  // ok

type Book struct {
    bytes.Buffer
    // other fields
}

// later
var b Book
b.Read(...)  // ok
b.String()   // ok
b.Write(...) // ok

Calling os.Exit or log.Fatal* inside functions other than main() creates three primary issues:

1. Non-obvious control flow: It becomes difficult to reason about the program's execution path if any function can abruptly terminate the process.
2. Difficult to test: A function that calls os.Exit will terminate the entire test process, making it impossible to test the function's error state without crashing the test runner and potentially skipping other tests.
3. Skipped cleanup: os.Exit terminates the program immediately without running any functions previously scheduled with defer. This can lead to resource leaks or incomplete cleanup tasks.

Embed types at the top of the field list, followed by an empty line before regular fields.

Guidelines for Embedding:

• Use embedding only when it provides tangible benefit (e.g., augmenting functionality).
• Do not embed sync.Mutex or other synchronization primitives, even on unexported types.
• Do not embed types purely for cosmetic reasons or to expose implementation details.
• Ensure embedding does not affect the outer type's zero value or copy semantics in a way that surprises users.

type countingWriteCloser struct {
    io.WriteCloser

    count int
}

func (w *countingWriteCloser) Write(bs []byte) (int, error) {
    w.count += len(bs)
    return w.WriteCloser.Write(bs)
}