Go Style Guide

https://google.github.io/styleguide/go/
Admin
The Go Style Guide codifies current best approaches for writing readable and idiomatic Go, aiming to...
Tokens:77,872
Snippets:537
Trust Score:8.3
Update:2 weeks ago
Show doc for...
Tokens:
Raw
### Explain cleanup with example for http.Get

Source: https://google.github.io/styleguide/go/best-practices.html

Example of explaining how to clean up resources when it is potentially unclear. Shows closing resp.Body and reading the body.

```go
// Good:
// Get issues a GET to the specified URL.
//
// When err is nil, resp always contains a non-nil resp.Body.
// Caller should close resp.Body when done reading from it.
//
//    resp, err := http.Get("http://example.com/")
//    if err != nil {
//        // handle error
//    }
//    defer resp.Body.Close()
//    body, err := io.ReadAll(resp.Body)
func (c *Client) Get(url string) (resp *Response, err error)

```

--------------------------------

### Create runnable example in Go test file

Source: https://google.github.io/styleguide/go/best-practices.html

Test files can contain runnable examples that appear attached to the corresponding documentation in godoc. This example shows a runnable example with an Output comment that godoc uses to verify the output.

```go
// Good:
func ExampleConfig_WriteTo() {
  cfg := &Config{
    Name: "example",
  }
  if err := cfg.WriteTo(os.Stdout); err != nil {
    log.Exitf("Failed to write config: %s", err)
  }
  // Output:
  // {
  //   "name": "example"
  // }
}


```

--------------------------------

### Good: explicit and commented Go alternatives

Source: https://google.github.io/styleguide/go/guide.html

Two Go examples that show more explicit and commented alternatives to the bad examples above. They make the logic clearer and call attention to important behavior.

```go
// Good:
u, err := db.UserByID(userID)
if err != nil {
    return fmt.Errorf("invalid origin user: %s", err)
}
user = u

```

```go
// Good:
// Gregorian leap years aren't just year%4 == 0.
// See https://en.wikipedia.org/wiki/Leap_year#Algorithm.
var (
    leap4   = year%4 == 0
    leap100 = year%100 == 0
    leap400 = year%400 == 0
)
leap := leap4 && (!leap100 || leap400)

```

--------------------------------

### External context vs. local names: bad example

Source: https://google.github.io/styleguide/go/decisions.html

Avoid repeating package context in type and method names; this example shows the repetitive style.

```go
// Bad:
// In package "ads/targeting/revenue/reporting"
type AdsTargetingRevenueReport struct{}

func (p *Project) ProjectName() string

```

--------------------------------

### External context vs. local names: good example

Source: https://google.github.io/styleguide/go/decisions.html

Omit redundant package context from type and method names; this is the improved version of the previous example.

```go
// Good:
// In package "ads/targeting/revenue/reporting"
type Report struct{}

func (p *Project) Name() string

```

--------------------------------

### Amortize common test setup with sync.Once

Source: https://google.github.io/styleguide/go/best-practices.html

Shows how to amortize expensive common test setup using a package-level struct with sync.Once. The first block defines the dataset holder and mustLoadDataset helper; the second shows multiple test functions calling it so the load cost is paid once. Note that common teardown is not handled, and sync.Once may be problematic if the setup relies on a context because racing calls cannot respect cancellation while waiting.

```go
// Good:
var dataset struct {
    once sync.Once
    data []byte
    err  error
}

func mustLoadDataset(t *testing.T) []byte {
    t.Helper()
    dataset.once.Do(func() {
        data, err := os.ReadFile("path/to/your/project/testdata/dataset")
        // dataset is defined as a package-level variable.
        dataset.data = data
        dataset.err = err
    })
    if err := dataset.err; err != nil {
        t.Fatalf("Could not load dataset: %v", err)
    }
    return dataset.data
}

```

```go
// Good:
func TestParseData(t *testing.T) {
    data := mustLoadDataset(t)

    // As documented above.
}

func TestListContents(t *testing.T) {
    data := mustLoadDataset(t)

    // As documented above.
}

func TestRegression682831(t *testing.T) {
    if got, want := guessOS("zpc79.example.com"), "grhat"; got != want {
        t.Errorf(`guessOS("zpc79.example.com") = %q, want %q`, got, want)
    }
}

```

--------------------------------

### Naming conventions: noun-like names

Source: https://google.github.io/styleguide/go/best-practices.html

Functions that return something should have noun-like names and avoid the prefix 'Get'. The good example uses JobName, while the bad example uses GetJobName.

```go
// Good:
func (c *Config) JobName(key string) (value string, ok bool)

```

```go
// Bad:
func (c *Config) GetJobName(key string) (value string, ok bool)

```

--------------------------------

### Production code example: creditcard package

Source: https://google.github.io/styleguide/go/best-practices.html

Example production code for a creditcard package, used as the basis for creating test helper packages.

```go
package creditcard

import (
    "errors"

    "path/to/money"
)

// ErrDeclined indicates that the issuer declines the charge.
var ErrDeclined = errors.New("creditcard: declined")

// Card contains information about a credit card, such as its issuer,
// expiration, and limit.
type Card struct {
    // omitted
}

// Service allows you to perform operations with credit cards against external
// payment processor vendors like charge, authorize, reimburse, and subscribe.
type Service struct {
    // omitted
}

func (s *Service) Charge(c *Card, amount money.Money) error { /* omitted */ }

```

--------------------------------

### Repetitive names in function: bad example

Source: https://google.github.io/styleguide/go/decisions.html

Avoid redundant names that repeat context or type; this example shows the repetitive style.

```go
// Bad:
func (db *DB) UserCount() (userCount int, err error) {
    var userCountInt64 int64
    if dbLoadError := db.LoadFromDatabase("count(distinct users)", &userCountInt64); dbLoadError != nil {
        return 0, fmt.Errorf("failed to load user count: %s", dbLoadError)
    }
    userCount = int(userCountInt64)
    return userCount, nil
}

```

--------------------------------

### External context vs. local names: good Connection

Source: https://google.github.io/styleguide/go/decisions.html

Use a concise type name that omits the package name; this is the improved version of the previous example.

```go
// Good:
// In package "sqldb"
type Connection struct{}

```

--------------------------------

### Avoid repetition: package name

Source: https://google.github.io/styleguide/go/best-practices.html

Avoid repeating the package name in function names. The bad example uses ParseYAMLConfig, while the good example uses Parse.

```go
// Bad:
package yamlconfig

func ParseYAMLConfig(input string) (*Config, error)

```

```go
// Good:
package yamlconfig

func Parse(input string) (*Config, error)

```

--------------------------------

### Document caller cleanup with Stop method

Source: https://google.github.io/styleguide/go/best-practices.html

Example of documenting explicit cleanup requirements that are up to the caller. Call Stop to release resources.

```go
// Good:
// NewTicker returns a new Ticker containing a channel that will send the
// current time on the channel after each tick.
//
// Call Stop to release the Ticker's associated resources when done.
func NewTicker(d Duration) *Ticker

func (*Ticker) Stop()

```

--------------------------------

### Avoid dot import (import .) - bad example

Source: https://google.github.io/styleguide/go/decisions.html

Discouraged use of the dot import feature, which brings identifiers without qualification and obscures their origin.

```go
// Bad:
package foo_test

import (
    "bar/testutil" // also imports "foo"
    . "foo"
)

var myThing = Bar() // Bar defined in package foo; no qualification needed.

```

--------------------------------

### Use t.Fatal only for setup failures

Source: https://google.github.io/styleguide/go/best-practices.html

Shows reserving t.Fatal for exceptional setup failures, such as failing to allocate a modem, while using t.Cleanup to release resources. The acceptance test itself should avoid t.Fatal unless a broken invariant is detected.

```go
func ExerciseGame(t *testing.T, cfg *Config, p chess.Player) error {
    t.Helper()

    if cfg.Simulation == Modem {
        conn, err := modempool.Allocate()
        if err != nil {
            t.Fatalf("No modem for the opponent could be provisioned: %v", err)
        }
        t.Cleanup(func() { modempool.Return(conn) })
    }
    // Run acceptance test (a whole game).
}
```

--------------------------------

### Document concurrency when API provides synchronization

Source: https://google.github.io/styleguide/go/best-practices.html

Example of documenting concurrency when synchronization is provided by the API. Stubby provides synchronization.

```go
// Good:
package fortune_go_proto

// NewFortuneTellerClient returns an *rpc.Client for the FortuneTeller service.
// It is safe for simultaneous use by multiple goroutines.
func NewFortuneTellerClient(cc *rpc.ClientConn) *FortuneTellerClient

```

--------------------------------

### Matching braces: multi-line literal good example

Source: https://google.github.io/styleguide/go/decisions.html

Multi-line literals should have the closing brace on a new line with the same indentation as the opening brace.

```go
// Good:
good := []*Type{
    {Key: "multi"},
    {Key: "line"},
}

```

--------------------------------

### Bad: EnableReplication with many parameters

Source: https://google.github.io/styleguide/go/best-practices.html

Shows the original function signature with many parameters, which is hard to use and extend. This is the 'Bad' example that motivates the variadic options pattern.

```go
// Bad:
func EnableReplication(ctx context.Context, config *placer.Config, primaryCells, readonlyCells []string, replicateExisting, overwritePolicies bool, replicationInterval time.Duration, copyWorkers int, healthWatcher health.Watcher) {
  ...
}

```

--------------------------------

### Document concurrency for interface with consumer requirements

Source: https://google.github.io/styleguide/go/best-practices.html

Example of documenting concurrency when the API consumes user-implemented types or interfaces and the interface's consumer has particular concurrency requirements.

```go
// Good:
package health

// A Watcher reports the health of some entity (usually a backend service).
//
// Watcher methods are safe for simultaneous use by multiple goroutines.
type Watcher interface {
    // Watch sends true on the passed-in channel when the Watcher's
    // status has changed.
    Watch(changed chan<- bool) (unwatch func())

    // Health returns nil if the entity being watched is healthy, or a
    // non-nil error explaining why the entity is not healthy.
    Health() error
}

```

--------------------------------

### Avoid t.Fatal in goroutines: use t.Errorf

Source: https://google.github.io/styleguide/go/best-practices.html

Use t.Errorf instead of t.Fatal in goroutines started by a test. The example shows a test that starts multiple goroutines and reports errors from them, while using t.Fatalf only in the test's own goroutine.

```go
// Good:
func TestRevEngine(t *testing.T) {
    engine, err := Start()
    if err != nil {
        t.Fatalf("Engine failed to start: %v", err)
    }

    num := 11
    var wg sync.WaitGroup
    wg.Add(num)
    for i := 0; i < num; i++ {
        go func() {
            defer wg.Done()
            if err := engine.Vroom(); err != nil {
                // This cannot be t.Fatalf.
                t.Errorf("No vroom left on engine: %v", err)
                return
            }
            if rpm := engine.Tachometer(); rpm > 1e6 {
                t.Errorf("Inconceivable engine rate: %d", rpm)
            }
        }()
    }
    wg.Wait()

    if seen := engine.NumVrooms(); seen != num {
        t.Errorf("engine.NumVrooms() = %d, want %d", seen, num)
    }
}

```

--------------------------------

### Custom TestMain with runMain for database setup

Source: https://google.github.io/styleguide/go/best-practices.html

Shows a custom TestMain entrypoint that sets up a database once for all tests and cleans it up via defer. It uses a separate runMain function to allow defers to execute before os.Exit, and logs fatal errors to STDERR.

```go
// Good:
var db *sql.DB

func TestInsert(t *testing.T) { /* omitted */ }

func TestSelect(t *testing.T) { /* omitted */ }

func TestUpdate(t *testing.T) { /* omitted */ }

func TestDelete(t *testing.T) { /* omitted */ }

// runMain sets up the test dependencies and eventually executes the tests.
// It is defined as a separate function to enable the setup stages to clearly
// defer their teardown steps.
func runMain(ctx context.Context, m *testing.M) (code int, err error) {
    ctx, cancel := context.WithCancel(ctx)
    defer cancel()

    d, err := setupDatabase(ctx)
    if err != nil {
        return 0, err
    }
    defer d.Close() // Expressly clean up database.
    db = d          // db is defined as a package-level variable.

    // m.Run() executes the regular, user-defined test functions.
    // Any defer statements that have been made will be run after m.Run()
    // completes.
    return m.Run(), nil
}

func TestMain(m *testing.M) {
    code, err := runMain(context.Background(), m)
    if err != nil {
        // Failure messages should be written to STDERR, which log.Fatal uses.
        log.Fatal(err)
    }
    // NOTE: defer statements do not run past here due to os.Exit
    //       terminating the process.
    os.Exit(code)
}

```

--------------------------------

### Bad: Multi-line function signature

Source: https://google.github.io/styleguide/go/decisions.html

Avoid breaking a function signature across lines because it can confuse indentation and make the body appear to start earlier. This example shows a multi-line signature that is discouraged.

```go
// Bad:
func (r *SomeType) SomeLongFunctionName(foo1, foo2, foo3 string,
    foo4, foo5, foo6 int) {
    foo7 := bar(foo1)
    // ...
}

```

--------------------------------

### Size hints and preallocation

Source: https://google.github.io/styleguide/go/best-practices.html

Demonstrates size hints and preallocation for slices and maps, with comments explaining the chosen capacities. Preallocating more than needed can waste memory or harm performance.

```go
// Good:
var (
    // Preferred buffer size for target filesystem: st_blksize.
    buf = make([]byte, 131072)
    // Typically process up to 8-10 elements per run (16 is a safe assumption).
    q = make([]Node, 0, 16)
    // Each shard processes shardSize (typically 32000+) elements.
    seen = make(map[string]bool, shardSize)
)

```

--------------------------------

### Repetitive names in function: good example

Source: https://google.github.io/styleguide/go/decisions.html

Omit names that are clear from context or usage; this is the improved version of the previous example.

```go
// Good:
func (db *DB) UserCount() (int, error) {
    var count int64
    if err := db.Load("count(distinct users)", &count); err != nil {
        return 0, fmt.Errorf("failed to load user count: %s", err)
    }
    return int(count), nil
}

```

--------------------------------

### Import proto and gRPC packages with pb and grpc suffixes

Source: https://google.github.io/styleguide/go/best-practices.html

Shows the recommended import naming convention for proto and gRPC generated packages, using the `pb` and `grpc` suffixes respectively.

```go
// Good:
import (
    foopb "path/to/package/foo_service_go_proto"
    foogrpc "path/to/package/foo_service_go_grpc"
)

```

--------------------------------

### MustXYZ helper for package-level initialization

Source: https://google.github.io/styleguide/go/decisions.html

Shows the recommended pattern for a MustXYZ helper that panics on error, used to initialize package-level variables at startup. The helper is called in a value context to set a package-level constant.

```go
// Good:
func MustParse(version string) *Version {
    v, err := Parse(version)
    if err != nil {
        panic(fmt.Sprintf("MustParse(%q) = _, %v", version, err))
    }
    return v
}

// Package level "constant". If we wanted to use `Parse`, we would have had to
// set the value in `init`.
var DefaultVersion = MustParse("1.2.3")

```

--------------------------------

### Import proto package with descriptive pb suffix

Source: https://google.github.io/styleguide/go/best-practices.html

Shows the recommended import naming convention for a proto package when the package name is not obvious, using the proto package name up to `_go` with a `pb` suffix.

```go
// Good:
import (
    pushqueueservicepb "path/to/package/push_queue_service_go_proto"
)

```

--------------------------------

### Use cmp and fmt for equality checks

Source: https://google.github.io/styleguide/go/decisions.html

Prefer using standard libraries like cmp and fmt for equality comparisons. This example compares a got value with a want value and reports a clear error message on mismatch.

```go
// Good:
var got BlogPost

want := BlogPost{
    Comments: 2,
    Body:     "Hello, world!",
}

if !cmp.Equal(got, want) {
    t.Errorf("Blog post = %v, want = %v", got, want)
}

```

--------------------------------

### Cuddled braces: correctly cuddled example

Source: https://google.github.io/styleguide/go/decisions.html

Cuddling is allowed when the inner values are literals and the indentation matches. This example shows correct cuddling.

```go
// Good:
good := []*Type{{ // Cuddled correctly
    Field: "value",
}, {
    Field: "value",
}}

```

--------------------------------

### Verbose logging with log.V: good and bad patterns

Source: https://google.github.io/styleguide/go/best-practices.html

Shows the recommended pattern for verbose logging with log.V to avoid expensive calls when verbosity is off, and the anti-pattern that calls sql.Explain unconditionally.

```go
// Good:
for _, sql := range queries {
  log.V(1).Infof("Handling %v", sql)
  if log.V(2) {
    log.Infof("Handling %v", sql.Explain())
  }
  sql.Run(...)
}

```

```go
// Bad:
// sql.Explain called even when this log is not printed.
log.V(2).Infof("Handling %v", sql.Explain())

```

--------------------------------

### Cuddled braces: bad example with variable

Source: https://google.github.io/styleguide/go/decisions.html

This bad example cuddles a variable 'first' with a literal, which is not allowed. Also the closing brace is on the same line as the value.

```go
// Bad:
bad := []*Type{
    first,
    {
        Field: "second",
    }}

```

--------------------------------

### Avoid repetition: return values

Source: https://google.github.io/styleguide/go/best-practices.html

Avoid repeating return value names and types. The bad example uses TransformToJSON, while the good example uses Transform.

```go
// Bad:
func TransformToJSON(input *Config) *jsonconfig.Config

```

```go
// Good:
func Transform(input *Config) *jsonconfig.Config

```

--------------------------------

### Avoid repetition: parameter names

Source: https://google.github.io/styleguide/go/best-practices.html

Avoid repeating variable names passed as parameters. The bad example uses OverrideFirstWithSecond, while the good example uses Override.

```go
// Bad:
func OverrideFirstWithSecond(dest, source *Config) error

```

```go
// Good:
func Override(dest, source *Config) error

```

--------------------------------

### Good: sidecar.Registry with explicit instance state

Source: https://google.github.io/styleguide/go/best-practices.html

Shows the recommended approach: expose a Registry type with a constructor and a Register method, letting clients create and pass instances instead of relying on package-level state.

```go
// Good:
// Package sidecar manages subprocesses that provide features for applications.
package sidecar

type Registry struct { plugins map[string]*Plugin }

func New() *Registry { return &Registry{plugins: make(map[string]*Plugin)} }

func (r *Registry) Register(name string, p *Plugin) error { ... }

```

--------------------------------

### Good: Calling EnableReplication with variadic options

Source: https://google.github.io/styleguide/go/best-practices.html

Shows how to call the refactored EnableReplication from another package, both with many options and with no options. Demonstrates the flexibility and simplicity of the variadic options pattern.

```go
// Good:
func foo(ctx context.Context) {
    // Complex call:
    storage.EnableReplication(ctx, config, []string{"po", "is", "ea"},
        storage.ReadonlyCells("ix", "gg"),
        storage.OverwritePolicies(true),
        storage.ReplicationInterval(1*time.Hour),
        storage.CopyWorkers(100),
        storage.HealthWatcher(watcher),
    )

    // Simple call:
    storage.EnableReplication(ctx, config, []string{"po", "is", "ea"})
}

```

--------------------------------

### Avoid repetition: method receiver

Source: https://google.github.io/styleguide/go/best-practices.html

Avoid repeating the method receiver name in method names. The bad example uses WriteConfigTo, while the good example uses WriteTo.

```go
// Bad:
func (c *Config) WriteConfigTo(w io.Writer) (int64, error)

```

```go
// Good:
func (c *Config) WriteTo(w io.Writer) (int64, error)

```

--------------------------------

### Package comment for main package

Source: https://google.github.io/styleguide/go/decisions.html

For main packages, use the name of the go_binary rule from the BUILD file instead of the package name. Capitalize the binary name even if it doesn't match the command-line spelling.

```go
// Good:
// The seed_generator command is a utility that generates a Finch seed file
// from a set of JSON study configs.
package main

```

--------------------------------

### Context as first parameter

Source: https://google.github.io/styleguide/go/decisions.html

Shows the required signature for functions that accept a context.Context: it must be the first parameter. The comment placeholder indicates where other arguments follow.

```go
func F(ctx context.Context /* other arguments */) {}

```

--------------------------------

### Matching braces: bad example with inner brace

Source: https://google.github.io/styleguide/go/decisions.html

Another bad example: the closing brace of the inner literal is on the same line as the value, breaking the brace matching rule.

```go
// Bad:
bad := []*Type{
    {
        Key: "value"},
}

```

--------------------------------

### Cuddled braces: not cuddled example

Source: https://google.github.io/styleguide/go/decisions.html

Cuddling braces (dropping whitespace) is only allowed when indentation matches and inner values are literals or proto builders. This example shows non-cuddled braces.

```go
// Good:
good := []*Type{
    { // Not cuddled
        Field: "value",
    },
    {
        Field: "value",
    },
}

```

--------------------------------

### Bad: Thick-client singleton (useradmin.Client)

Source: https://google.github.io/styleguide/go/best-practices.html

Shows a thick-client singleton pattern where a package-level variable holds a client and is lazily initialized. This global state can cause reliability issues and makes testing with different client instances difficult.

```go
// Bad:
package useradmin

var client pb.UserAdminServiceClientInterface

func Client() *pb.UserAdminServiceClient {
    if client == nil {
        client = ...  // Set up client.
    }
    return client
}

```

--------------------------------

### Omit zero-value fields in struct literals (leveldb Options, bad vs good)

Source: https://google.github.io/styleguide/go/decisions.html

Shows the recommended style of omitting zero-value fields from struct literals when clarity is not lost. The bad example explicitly lists all zero-value fields, while the good example omits them to draw attention to the only option being specified. The example uses the leveldb library's Options struct.

```go
// Bad:
import (
  "github.com/golang/leveldb"
  "github.com/golang/leveldb/db"
)

ldb := leveldb.Open("/my/table", &db.Options{
    BlockSize: 1<<16,
    ErrorIfDBExists: true,

    // These fields all have their zero values.
    BlockRestartInterval: 0,
    Comparer: nil,
    Compression: nil,
    FileSystem: nil,
    FilterPolicy: nil,
    MaxOpenFiles: 0,
    WriteBufferSize: 0,
    VerifyChecksums: false,
})

```

```go
// Good:
import (
  "github.com/golang/leveldb"
  "github.com/golang/leveldb/db"
)

ldb := leveldb.Open("/my/table", &db.Options{
    BlockSize: 1<<16,
    ErrorIfDBExists: true,
})

```

--------------------------------

### Use explicit qualification instead of dot import - good example

Source: https://google.github.io/styleguide/go/decisions.html

Preferred alternative to the dot import, using explicit qualification (foo.Bar()) to make the source of the identifier clear.

```go
// Good:
package foo_test

import (
    "bar/testutil" // also imports "foo"
    "foo"
)

var myThing = foo.Bar()

```

--------------------------------

### Good: Passing sidecar.Registry as explicit dependency

Source: https://google.github.io/styleguide/go/best-practices.html

Shows how a client instantiates a *sidecar.Registry and passes it as an explicit dependency (via a struct field) to the application, avoiding global state.

```go
// Good:
package main

func main() {
  sidecars := sidecar.New()
  if err := sidecars.Register("Cloud Logger", cloudlogger.New()); err != nil {
    log.Exitf("Could not setup cloud logger: %v", err)
  }
  cfg := &myapp.Config{Sidecars: sidecars}
  myapp.Run(context.Background(), cfg)
}

```

--------------------------------

### Use non-prefixed spy variable name in test (bad example)

Source: https://google.github.io/styleguide/go/best-practices.html

Test using a spy for CreditCard with a non-prefixed variable name 'cc', which is less clear because it does not differentiate the double from production types. This is shown as a bad example.

```go
// Bad:
package payment

import "path/to/creditcardtest"

func TestProcessor(t *testing.T) {
    var cc creditcardtest.Spy

    proc := &Processor{CC: cc}

    // declarations omitted: card and amount
    if err := proc.Process(card, amount); err != nil {
        t.Errorf("proc.Process(card, amount) = %v, want nil", err)
    }

    charges := []creditcardtest.Charge{
        {Card: card, Amount: amount},
    }

    if got, want := cc.Charges, charges; !cmp.Equal(got, want) {
        t.Errorf("cc.Charges = %v, want %v", got, want)
    }
}

```

--------------------------------

### Call function with option structure

Source: https://google.github.io/styleguide/go/best-practices.html

Example of calling a function with an option structure from a different package. Shows both a complex call with many options and a simple call with only required fields.

```go
// Good:
func foo(ctx context.Context) {
    // Complex call:
    storage.EnableReplication(ctx, storage.ReplicationOptions{
        Config:              config,
        PrimaryRegions:      []string{"us-east1", "us-central2", "us-west3"},
        ReadonlyRegions:     []string{"us-east5", "us-central6"},
        OverwritePolicies:   true,
        ReplicationInterval: 1 * time.Hour,
        CopyWorkers:         100,
        HealthWatcher:       watcher,
    })

    // Simple call:
    storage.EnableReplication(ctx, storage.ReplicationOptions{
        Config:         config,
        PrimaryRegions: []string{"us-east1", "us-central2", "us-west3"},
    })
}

```

--------------------------------

### Test helper error handling: t.Fatalf vs returning error

Source: https://google.github.io/styleguide/go/best-practices.html

Shows the recommended pattern for test helpers that must fail the test when setup fails, using t.Fatalf with a descriptive message, versus the discouraged pattern of returning an error to the test. The good version keeps the calling side cleaner and provides clear failure context.

```go
// Good:
func mustAddGameAssets(t *testing.T, dir string) {
    t.Helper()
    if err := os.WriteFile(path.Join(dir, "pak0.pak"), pak0, 0644); err != nil {
        t.Fatalf("Setup failed: could not write pak0 asset: %v", err)
    }
    if err := os.WriteFile(path.Join(dir, "pak1.pak"), pak1, 0644); err != nil {
        t.Fatalf("Setup failed: could not write pak1 asset: %v", err)
    }
}

```

```go
// Bad:
func addGameAssets(t *testing.T, dir string) error {
    t.Helper()
    if err := os.WriteFile(path.Join(d, "pak0.pak"), pak0, 0644); err != nil {
        return err
    }
    if err := os.WriteFile(path.Join(d, "pak1.pak"), pak1, 0644); err != nil {
        return err
    }
    return nil
}

```

--------------------------------

### Go flag naming conventions: good vs bad

Source: https://google.github.io/styleguide/go/decisions.html

Shows the recommended and discouraged ways to define command-line flags in Go. The good example uses snake_case for the flag name and camelCase for the variable, while the bad example reverses these conventions. Flags should only be defined in package main or equivalent.

```go
// Good:
var (
    pollInterval = flag.Duration("poll_interval", time.Minute, "Interval to use for polling.")
)

```

```go
// Bad:
var (
    poll_interval = flag.Int("pollIntervalSeconds", 60, "Interval to use for polling in seconds.")
)

```

--------------------------------

### Prefer strings.Builder for piecemeal string construction

Source: https://google.github.io/styleguide/go/best-practices.html

Prefer strings.Builder when building a string bit-by-bit. It takes amortized linear time, whereas + and fmt.Sprintf take quadratic time when called sequentially to form a larger string.

```go
// Good:
b := new(strings.Builder)
for i, d := range digitsOfPi {
    fmt.Fprintf(b, "the %d digit of pi is: %d\n", i, d)
}
str := b.String()

```

--------------------------------

### Good: table-driven tests with separate codex setup

Source: https://google.github.io/styleguide/go/decisions.html

Recommended table-driven test structure that keeps the codex type out of the test case struct. Two test functions use a real Codex (slow setup) and a fake Codex (fast approximation) respectively, with each row identified by a name field and subtests via t.Run.

```go
// Good:
type decodeCase struct {
    name   string
    input  string
    output string
    err    error
}

func TestDecode(t *testing.T) {
    // setupCodex is slow as it creates a real Codex for the test.
    codex := setupCodex(t)

    var tests []decodeCase // rows omitted for brevity

    for _, test := range tests {
        t.Run(test.name, func(t *testing.T) {
            output, err := Decode(test.input, codex)
            if got, want := output, test.output; got != want {
                t.Errorf("Decode(%q) = %v, want %v", test.input, got, want)
            }
            if got, want := err, test.err; !cmp.Equal(got, want) {
                t.Errorf("Decode(%q) err %q, want %q", test.input, got, want)
            }
        })
    }
}

func TestDecodeWithFake(t *testing.T) {
    // A fakeCodex is a fast approximation of a real Codex.
    codex := newFakeCodex()

    var tests []decodeCase // rows omitted for brevity

    for _, test := range tests {
        t.Run(test.name, func(t *testing.T) {
            output, err := Decode(test.input, codex)
            if got, want := output, test.output; got != want {
                t.Errorf("Decode(%q) = %v, want %v", test.input, got, want)
            }
            if got, want := err, test.err; !cmp.Equal(got, want) {
                t.Errorf("Decode(%q) err %q, want %q", test.input, got, want)
            }
        })
    }
}

```

--------------------------------

### Test helper with context first

Source: https://google.github.io/styleguide/go/decisions.html

Illustrates the recommended pattern for test helpers: pass context.Context as the first parameter, followed by the testing.TB. This follows the convention that context comes first in all functions, including test helpers.

```go
// Good:
func readTestFile(ctx context.Context, t *testing.T, path string) string {}

```

--------------------------------

### Cuddled braces: variable cannot be cuddled

Source: https://google.github.io/styleguide/go/decisions.html

Variables or other expressions cannot be cuddled. This example shows a variable 'first' that cannot be cuddled, while the literal can be.

```go
// Good:
good := []*Type{
    first, // Can't be cuddled
    {Field: "second"},
}

```
Tokens:
Raw