Home Business uber-go/guide

uber-go/guide

by admin2 admin2
59 views
uber-go/guide

Table of Contents
Introduction
Guidelines
Pointers to Interfaces
Receivers and Interfaces
Zero-value Mutexes are Valid
Copy Slices and Maps at Boundaries
Defer to Clean Up
Channel Size is One or None
Start Enums at One
Error Types
Error Wrapping
Handle Type Assertion Failures
Don’t Panic
Use go.uber.org/atomic

Performance
Prefer strconv over fmt
Avoid string-to-byte conversion

Style
Group Similar Declarations
Import Group Ordering
Package Names
Function Names
Import Aliasing
Function Grouping and Ordering
Reduce Nesting
Unnecessary Else
Top-level Variable Declarations
Prefix Unexported Globals with _
Embedding in Structs
Use Field Names to initialize Structs
Local Variable Declarations
nil is a valid slice
Reduce Scope of Variables
Avoid Naked Parameters
Use Raw String Literals to Avoid Escaping
Initializing Struct References
Format Strings outside Printf
Naming Printf-style Functions

Patterns
Test Tables
Functional Options

Introduction
Styles are the conventions that govern our code. The term style is a bit of a
misnomer, since these conventions cover far more than just source file
formatting—gofmt handles that for us.
The goal of this guide is to manage this complexity by describing in detail the
Dos and Don’ts of writing Go code at Uber. These rules exist to keep the code
base manageable while still allowing engineers to use Go language features
productively.
This guide was originally created by Prashant Varanasi and Simon Newton as
a way to bring some colleagues up to speed with using Go. Over the years it has
been amended based on feedback from others.
This documents idiomatic conventions in Go code that we follow at Uber. A lot
of these are general guidelines for Go, while others extend upon external
resources:
Effective Go
The Go common mistakes guide
All code should be error-free when run through golint and go vet. We
recommend setting up your editor to:
Run goimports on save
Run golint and go vet to check for errors
You can find information in editor support for Go tools here:
https://github.com/golang/go/wiki/IDEsAndTextEditorPlugins
Guidelines
Pointers to Interfaces
You almost never need a pointer to an interface. You should be passing
interfaces as values—the underlying data can still be a pointer.
An interface is two fields:
A pointer to some type-specific information. You can think of this as
“type.”
Data pointer. If the data stored is a pointer, it’s stored directly. If
the data stored is a value, then a pointer to the value is stored.
If you want interface methods to modify the underlying data, you must use a
pointer.
Receivers and Interfaces
Methods with value receivers can be called on pointers as well as values.
For example,
type S struct {
data string
}

func (s S) Read() string {
return s.data
}

func (s *S) Write(str string) {
s.data = str
}

sVals := map[int]S{1: {“A”}}

// You can only call Read using a value
sVals[1].Read()

// This will not compile:
// sVals[0].Write(“test”)

sPtrs := map[int]*S{1: {“A”}}

// You can call both Read and Write using a pointer
sPtrs[1].Read()
sPtrs[1].Write(“test”)
Similarly, an interface can be satisfied by a pointer, even if the method has a
value receiver.
type F interface {
f()
}

type S1 struct{}

func (s S1) f() {}

type S2 struct{}

func (s *S2) f() {}

s1Val := S1{}
s1Ptr := &S1{}
s2Val := S2{}
s2Ptr := &S2{}

var i F
i = s1Val
i = s1Ptr
i = s2Ptr

// The following doesn’t compile, since s2Val is a value, and there is no value receiver for f.
// i = s2Val
Effective Go has a good write up on Pointers vs. Values.
Zero-value Mutexes are Valid
The zero-value of sync.Mutex and sync.RWMutex is valid, so you almost
never need a pointer to a mutex.
BadGood
mu := new(sync.Mutex)
mu.Lock()

var mu sync.Mutex
mu.Lock()
If you use a struct by pointer, then the mutex can be a non-pointer field or,
preferably, embedded directly into the struct.

type smap struct {
sync.Mutex

data map[string]string
}

func newSMap() *smap {
return &smap{
data: make(map[string]string),
}
}

func (m *smap) Get(k string) string {
m.Lock()
defer m.Unlock()

return m.data[k]
}

type SMap struct {
mu sync.Mutex

data map[string]string
}

func NewSMap() *SMap {
return &SMap{
data: make(map[string]string),
}
}

func (m *SMap) Get(k string) string {
m.mu.Lock()
defer m.mu.Unlock()

return m.data[k]
}
Embed for private types or types that need to implement the Mutex interface.
For exported types, use a private lock.
Copy Slices and Maps at Boundaries
Slices and maps contain pointers to the underlying data so be wary of scenarios
when they need to be copied.
Receiving Slices and Maps
Keep in mind that users can modify a map or slice you received as an argument
if you store a reference to it.
Bad Good
func (d *Driver) SetTrips(trips []Trip) {
d.trips = trips
}

trips := …
d1.SetTrips(trips)

// Did you mean to modify d1.trips?
trips[0] = …

func (d *Driver) SetTrips(trips []Trip) {
d.trips = make([]Trip, len(trips))
copy(d.trips, trips)
}

trips := …
d1.SetTrips(trips)

// We can now modify trips[0] without affecting d1.trips.
trips[0] = …

Returning Slices and Maps
Similarly, be wary of user modifications to maps or slices exposing internal
state.
BadGood
type Stats struct {
sync.Mutex

counters map[string]int
}

// Snapshot returns the current stats.
func (s *Stats) Snapshot() map[string]int {
s.Lock()
defer s.Unlock()

return s.counters
}

// snapshot is no longer protected by the lock!
snapshot := stats.Snapshot()

type Stats struct {
sync.Mutex

counters map[string]int
}

func (s *Stats) Snapshot() map[string]int {
s.Lock()
defer s.Unlock()

result := make(map[string]int, len(s.counters))
for k, v := range s.counters {
result[k] = v
}
return result
}

// Snapshot is now a copy.
snapshot := stats.Snapshot()
Defer to Clean Up
Use defer to clean up resources such as files and locks.
BadGood
p.Lock()
if p.count < 10 { p.Unlock() return p.count } p.count++ newCount := p.count p.Unlock() return newCount // easy to miss unlocks due to multiple returns p.Lock() defer p.Unlock() if p.count < 10 { return p.count } p.count++ return p.count // more readable Defer has an extremely small overhead and should be avoided only if you can prove that your function execution time is in the order of nanoseconds. The readability win of using defers is worth the miniscule cost of using them. This is especially true for larger methods that have more than simple memory accesses, where the other computations are more significant than the defer. Channel Size is One or None Channels should usually have a size of one or be unbuffered. By default, channels are unbuffered and have a size of zero. Any other size must be subject to a high level of scrutiny. Consider how the size is determined, what prevents the channel from filling up under load and blocking writers, and what happens when this occurs. BadGood // Ought to be enough for anybody! c := make(chan int, 64) // Size of one c := make(chan int, 1) // or // Unbuffered channel, size of zero c := make(chan int) Start Enums at One The standard way of introducing enumerations in Go is to declare a custom type and a const group with iota. Since variables have a 0 default value, you should usually start your enums on a non-zero value. BadGood type Operation int const ( Add Operation = iota Subtract Multiply ) // Add=0, Subtract=1, Multiply=2 type Operation int const ( Add Operation = iota + 1 Subtract Multiply ) // Add=1, Subtract=2, Multiply=3 There are cases where using the zero value makes sense, for example when the zero value case is the desirable default behavior. type LogOutput int const ( LogToStdout LogOutput = iota LogToFile LogToRemote ) // LogToStdout=0, LogToFile=1, LogToRemote=2 Error Types There are various options for declaring errors: errors.New for errors with simple static strings fmt.Errorf for formatted error strings Custom types that implement an Error() method Wrapped errors using "pkg/errors".Wrap When returning errors, consider the following to determine the best choice: Is this a simple error that needs no extra information? If so, errors.New should suffice. Do the clients need to detect and handle this error? If so, you should use a custom type, and implement the Error() method. Are you propagating an error returned by a downstream function? If so, check the section on error wrapping. Otherwise, fmt.Errorf is okay. If the client needs to detect the error, and you have created a simple error using errors.New, use a var for the error. BadGood // package foo func Open() error { return errors.New("could not open") } // package bar func use() { if err := foo.Open(); err != nil { if err.Error() == "could not open" { // handle } else { panic("unknown error") } } } // package foo var ErrCouldNotOpen = errors.New("could not open") func Open() error { return ErrCouldNotOpen } // package bar if err := foo.Open(); err != nil { if err == foo.ErrCouldNotOpen { // handle } else { panic("unknown error") } } If you have an error that clients may need to detect, and you would like to add more information to it (e.g., it is not a static string), then you should use a custom type. BadGood func open(file string) error { return fmt.Errorf("file %q not found", file) } func use() { if err := open(); err != nil { if strings.Contains(err.Error(), "not found") { // handle } else { panic("unknown error") } } } type errNotFound struct { file string } func (e errNotFound) Error() string { return fmt.Sprintf("file %q not found", e.file) } func open(file string) error { return errNotFound{file: file} } func use() { if err := open(); err != nil { if _, ok := err.(errNotFound); ok { // handle } else { panic("unknown error") } } } Be careful with exporting custom error types directly since they become part of the public API of the package. It is preferable to expose matcher functions to check the error instead. // package foo type errNotFound struct { file string } func (e errNotFound) Error() string { return fmt.Sprintf("file %q not found", e.file) } func IsNotFoundError(err error) bool { _, ok := err.(errNotFound) return ok } func Open(file string) error { return errNotFound{file: file} } // package bar if err := foo.Open("foo"); err != nil { if foo.IsNotFoundError(err) { // handle } else { panic("unknown error") } } Error Wrapping There are three main options for propagating errors if a call fails: Return the original error if there is no additional context to add and you want to maintain the original error type. Add context using "pkg/errors".Wrap so that the error message provides more context and "pkg/errors".Cause can be used to extract the original error. Use fmt.Errorf if the callers do not need to detect or handle that specific error case. It is recommended to add context where possible so that instead of a vague error such as "connection refused", you get more useful errors such as "call service foo: connection refused". When adding context to returned errors, keep the context succinct by avoiding phrases like "failed to", which state the obvious and pile up as the error percolates up through the stack: BadGood s, err := store.New() if err != nil { return fmt.Errorf( "failed to create new store: %s", err) } s, err := store.New() if err != nil { return fmt.Errorf( "new store: %s", err) } failed to x: failed to y: failed to create new store: the error x: y: new store: the error However once the error is sent to another system, it should be clear the message is an error (e.g. an err tag or "Failed" prefix in logs). See also Don't just check errors, handle them gracefully. Handle Type Assertion Failures The single return value form of a type assertion will panic on an incorrect type. Therefore, always use the "comma ok" idiom. BadGood t := i.(string) t, ok := i.(string) if !ok { // handle the error gracefully } Don't Panic Code running in production must avoid panics. Panics are a major source of cascading failures. If an error occurs, the function must return an error and allow the caller to decide how to handle it. BadGood func foo(bar string) { if len(bar) == 0 { panic("bar must not be empty") } // ... } func main() { if len(os.Args) != 2 { fmt.Println("USAGE: foo ") os.Exit(1) } foo(os.Args[1]) } func foo(bar string) error { if len(bar) == 0 return errors.New("bar must not be empty") } // ... return nil } func main() { if len(os.Args) != 2 { fmt.Println("USAGE: foo ") os.Exit(1) } if err := foo(os.Args[1]); err != nil { panic(err) } } Panic/recover is not an error handling strategy. A program must panic only when something irrecoverable happens such as a nil dereference. An exception to this is program initialization: bad things at program startup that should abort the program may cause panic. var _statusTemplate = template.Must(template.New("name").Parse("_statusHTML")) Even in tests, prefer t.Fatal or t.FailNow over panics to ensure that the test is marked as failed. BadGood // func TestFoo(t *testing.T) f, err := ioutil.TempFile("", "test") if err != nil { panic("failed to set up test") } // func TestFoo(t *testing.T) f, err := ioutil.TempFile("", "test") if err != nil { t.Fatal("failed to set up test") } Use go.uber.org/atomic Atomic operations with the sync/atomic package operate on the raw types (int32, int64, etc.) so it is easy to forget to use the atomic operation to read or modify the variables. go.uber.org/atomic adds type safety to these operations by hiding the underlying type. Additionally, it includes a convenient atomic.Bool type. BadGood type foo struct { running int32 // atomic } func (f* foo) start() { if atomic.SwapInt32(&f.running, 1) == 1 { // already running… return } // start the Foo } func (f *foo) isRunning() bool { return f.running == 1 // race! } type foo struct { running atomic.Bool } func (f *foo) start() { if f.running.Swap(true) { // already running… return } // start the Foo } func (f *foo) isRunning() bool { return f.running.Load() } Performance Performance-specific guidelines apply only to the hot path. Prefer strconv over fmt When converting primitives to/from strings, strconv is faster than fmt. BadGood for i := 0; i < b.N; i++ { s := fmt.Sprint(rand.Int()) } for i := 0; i < b.N; i++ { s := strconv.Itoa(rand.Int()) } BenchmarkFmtSprint-4 143 ns/op 2 allocs/op BenchmarkStrconv-4 64.2 ns/op 1 allocs/op Avoid string-to-byte conversion Do not create byte slices from a fixed string repeatedly. Instead, perform the conversion once and capture the result. BadGood for i := 0; i < b.N; i++ { w.Write([]byte("Hello world")) } data := []byte("Hello world") for i := 0; i < b.N; i++ { w.Write(data) } BenchmarkBad-4 50000000 22.2 ns/op BenchmarkGood-4 500000000 3.25 ns/op Style Group Similar Declarations Go supports grouping similar declarations. BadGood import "a" import "b" import ( "a" "b" ) This also applies to constants, variables, and type declarations. BadGood const a = 1 const b = 2 var a = 1 var b = 2 type Area float64 type Volume float64 const ( a = 1 b = 2 ) var ( a = 1 b = 2 ) type ( Area float64 Volume float64 ) Only group related declarations. Do not group declarations that are unrelated. BadGood type Operation int const ( Add Operation = iota + 1 Subtract Multiply ENV_VAR = "MY_ENV" ) type Operation int const ( Add Operation = iota + 1 Subtract Multiply ) const ENV_VAR = "MY_ENV" Groups are not limited in where they can be used. For example, you can use them inside of functions. BadGood func f() string { var red = color.New(0xff0000) var green = color.New(0x00ff00) var blue = color.New(0x0000ff) ... } func f() string { var ( red = color.New(0xff0000) green = color.New(0x00ff00) blue = color.New(0x0000ff) ) ... } Import Group Ordering There should be two import groups: Standard library Everything else This is the grouping applied by goimports by default. BadGood import ( "fmt" "os" "go.uber.org/atomic" "golang.org/x/sync/errgroup" ) import ( "fmt" "os" "go.uber.org/atomic" "golang.org/x/sync/errgroup" ) Package Names When naming packages, choose a name that is, All lower-case. No capitals or underscores. Does not need to be renamed using named imports at most call sites. Short and succint. Remember that the name is identified in full at every call site. Not plural. For example, net/url, not net/urls. Not "common", "util", "shared", or "lib". These are bad, uninformative names. See also Package Names and Style guideline for Go packages. Function Names We follow the Go community's convention of using MixedCaps for function names. An exception is made for test functions, which may contain underscores for the purpose of grouping related test cases, e.g., TestMyFunction_WhatIsBeingTested. Import Aliasing Import aliasing must be used if the package name does not match the last element of the import path. import ( "net/http" client "example.com/client-go" trace "example.com/trace/v2" ) In all other scenarios, import aliases should be avoided unless there is a direct conflict between imports. BadGood import ( "fmt" "os" nettrace "golang.net/x/trace" ) import ( "fmt" "os" "runtime/trace" nettrace "golang.net/x/trace" ) Function Grouping and Ordering Functions should be sorted in rough call order. Functions in a file should be grouped by receiver. Therefore, exported functions should appear first in a file, after struct, const, var definitions. A newXYZ()/NewXYZ() may appear after the type is defined, but before the rest of the methods on the receiver. Since functions are grouped by receiver, plain utility functions should appear towards the end of the file. BadGood func (s *something) Cost() { return calcCost(s.weights) } type something struct{ ... } func calcCost(n int[]) int {...} func (s *something) Stop() {...} func newSomething() *something { return &something{} } type something struct{ ... } func newSomething() *something { return &something{} } func (s *something) Cost() { return calcCost(s.weights) } func (s *something) Stop() {...} func calcCost(n int[]) int {...} Reduce Nesting Code should reduce nesting where possible by handling error cases/special conditions first and returning early or continuing the loop. Reduce the amount of code that is nested multiple levels. BadGood for _, v := range data { if v.F1 == 1 { v = process(v) if err := v.Call(); err == nil { v.Send() } else { return err } } else { log.Printf("Invalid v: %v", v) } } for _, v := range data { if v.F1 != 1 { log.Printf("Invalid v: %v", v) continue } v = process(v) if err := v.Call(); err != nil { return err } v.Send() } Unnecessary Else If a variable is set in both branches of an if, it can be replaced with a single if. BadGood var a int if b { a = 100 } else { a = 10 } a := 10 if b { a = 100 } Top-level Variable Declarations At the top level, use the standard var keyword. Do not specify the type, unless it is not the same type as the expression. BadGood var _s string = F() func F() string { return "A" } var _s = F() // Since F already states that it returns a string, we don't need to specify // the type again. func F() string { return "A" } Specify the type if the type of the expression does not match the desired type exactly. type myError struct{} func (myError) Error() string { return "error" } func F() myError { return myError{} } var _e error = F() // F returns an object of type myError but we want error. Prefix Unexported Globals with _ Prefix unexported top-level vars and consts with _ to make it clear when they are used that they are global symbols. Exception: Unexported error values, which should be prefixed with err. Rationale: Top-level variables and constants have a package scope. Using a generic name makes it easy to accidentally use the wrong value in a different file. BadGood // foo.go const ( defaultPort = 8080 defaultUser = "user" ) // bar.go func Bar() { defaultPort := 9090 ... fmt.Println("Default port", defaultPort) // We will not see a compile error if the first line of // Bar() is deleted. } // foo.go const ( _defaultPort = 8080 _defaultUser = "user" ) Embedding in Structs Embedded types (such as mutexes) should be at the top of the field list of a struct, and there must be an empty line separating embedded fields from regular fields. BadGood type Client struct { version int http.Client } type Client struct { http.Client version int } Use Field Names to initialize Structs You should almost always specify field names when initializing structs. This is now enforced by go vet. BadGood k := User{"John", "Doe", true} k := User{ FirstName: "John", LastName: "Doe", Admin: true, } Exception: Field names may be omitted in test tables when there are 3 or fewer fields. tests := []struct{ }{ op Operation want string }{ {Add, "add"}, {Subtract, "subtract"}, } Local Variable Declarations Short variable declarations (:=) should be used if a variable is being set to some value explicitly. BadGood var s = "foo" s := "foo" However, there are cases where the default value is clearer when the var keyword is use. Declaring Empty Slices, for example. BadGood func f(list []int) { filtered := []int{} for _, v := range list { if v > 10 {
filtered = append(filtered, v)
}
}
}

func f(list []int) {
var filtered []int
for _, v := range list {
if v > 10 {
filtered = append(filtered, v)
}
}
}
nil is a valid slice
nil is a valid slice of length 0. This means that,

You should not return a slice of length zero explicitly. Return nil
instead.
BadGood
if x == “” {
return []int{}
}

if x == “” {
return nil
}

To check if a slice is empty, always use len(s) == 0. Do not check for
nil.
BadGood
func isEmpty(s []string) bool {
return s == nil
}

func isEmpty(s []string) bool {
return len(s) == 0
}

The zero value (a slice declared with var) is usable immediately without
make().
BadGood
nums := []int{}
// or, nums := make([]int)

if add1 {
nums = append(nums, 1)
}

if add2 {
nums = append(nums, 2)
}

var nums []int

if add1 {
nums = append(nums, 1)
}

if add2 {
nums = append(nums, 2)
}

Reduce Scope of Variables
Where possible, reduce scope of variables. Do not reduce the scope if it
conflicts with Reduce Nesting.
BadGood
err := f.Close()
if err != nil {
return err
}

if err := f.Close(); err != nil {
return err
}
If you need a result of a function call outside of the if, then you should not
try to reduce the scope.
BadGood
if f, err := os.Open(“f”); err == nil {
_, err = io.WriteString(f, “data”)
if err != nil {
return err
}
return f.Close()
} else {
return err
}

f, err := os.Open(“f”)
if err != nil {
return err
}

if _, err := io.WriteString(f, “data”); err != nil {
return err
}

return f.Close()
Avoid Naked Parameters
Naked parameters in function calls can hurt readability. Add C-style comments
(/* … */) for parameter names when their meaning is not obvious.
BadGood
// func printInfo(name string, isLocal, done bool)

printInfo(“foo”, true, true)

// func printInfo(name string, isLocal, done bool)

printInfo(“foo”, true /* isLocal */, true /* done */)
Better yet, replace naked bool types with custom types for more readable and
type-safe code. This allows more than just two states (true/false) for that
parameter in the future.
type Region int

const (
UnknownRegion Region = iota
Local
)

type Status int

const (
StatusReady = iota + 1
StatusDone
// Maybe we will have a StatusInProgress in the future.
)

func printInfo(name string, region Region, status Status)
Use Raw String Literals to Avoid Escaping
Go supports raw string literals,
which can span multiple lines and include quotes. Use these to avoid
hand-escaped strings which are much harder to read.
BadGood
wantError := “unknown name:”test””

wantError := `unknown error:”test”`
Initializing Struct References
Use &T{} instead of new(T) when initializing struct references so that it
is consistent with the struct initialization.
BadGood
sval := T{Name: “foo”}

// inconsistent
sptr := new(T)
sptr.Name = “bar”

sval := T{Name: “foo”}

sptr := &T{Name: “bar”}
Format Strings outside Printf
If you declare format strings for Printf-style functions outside a string
literal, make them const values.
This helps go vet perform static analysis of the format string.
BadGood
msg := “unexpected values %v, %vn”
fmt.Printf(msg, 1, 2)

const msg = “unexpected values %v, %vn”
fmt.Printf(msg, 1, 2)
Naming Printf-style Functions
When you declare a Printf-style function, make sure that go vet can detect
it and check the format string.
This means that you should use pre-defined Printf-style function
names if possible. go vet will check these by default. See Printf family
for more information.
If using the pre-defined names is not an option, end the name you choose with
f: Wrapf, not Wrap. go vet can be asked to check specific Printf-style
names but they must end with f.
$ go vet -printfuncs=wrapf,statusf
See also go vet: Printf family check.
Patterns
Test Tables
Use table-driven tests with subtests to avoid duplicating code when the core
test logic is repetitive.
BadGood
// func TestSplitHostPort(t *testing.T)

host, port, err := net.SplitHostPort(“192.0.2.0:8000”)
require.NoError(t, err)
assert.Equal(t, “192.0.2.0”, host)
assert.Equal(t, “8000”, port)

host, port, err = net.SplitHostPort(“192.0.2.0:http”)
require.NoError(t, err)
assert.Equal(t, “192.0.2.0”, host)
assert.Equal(t, “http”, port)

host, port, err = net.SplitHostPort(“:8000”)
require.NoError(t, err)
assert.Equal(t, “”, host)
assert.Equal(t, “8000”, port)

host, port, err = net.SplitHostPort(“1:8”)
require.NoError(t, err)
assert.Equal(t, “1”, host)
assert.Equal(t, “8”, port)

// func TestSplitHostPort(t *testing.T)

tests := []struct{
give string
wantHost string
wantPort string
}{
{
give: “192.0.2.0:8000”,
wantHost: “192.0.2.0”,
wantPort: “8000”,
},
{
give: “192.0.2.0:http”,
wantHost: “192.0.2.0”,
wantPort: “http”,
},
{
give: “:8000”,
wantHost: “”,
wantPort: “8000”,
},
{
give: “1:8”,
wantHost: “1”,
wantPort: “8”,
},
}

for _, tt := range tests {
t.Run(tt.give, func(t *testing.T) {
host, port, err := net.SplitHostPort(tt.give)
require.NoError(t, err)
assert.Equal(t, tt.wantHost, host)
assert.Equal(t, tt.wantPort, port)
})
}
Test tables make it easier to add context to error messages, reduce duplicate
logic, and add new test cases.
We follow the convention that the slice of structs is referred to as tests
and each test case tt. Further, we encourage explicating the input and output
values for each test case with give and want prefixes.
tests := []struct{
give string
wantHost string
wantPort string
}{
// …
}

for _, tt := range tests {
// …
}
Functional Options
Functional options is a pattern in which you declare an opaque Option type
that records information in some internal struct. You accept a variadic number
of these options and act upon the full information recorded by the options on
the internal struct.
Use this pattern for optional arguments in constructors and other public APIs
that you foresee needing to expand, especially if you already have three or
more arguments on those functions.
BadGood
// package db

func Connect(
addr string,
timeout time.Duration,
caching bool,
) (*Connection, error) {
// …
}

// Timeout and caching must always be provided,
// even if the user wants to use the default.

db.Connect(addr, db.DefaultTimeout, db.DefaultCaching)
db.Connect(addr, newTimeout, db.DefaultCaching)
db.Connect(addr, db.DefaultTimeout, false /* caching */)
db.Connect(addr, newTimeout, false /* caching */)

type options struct {
timeout time.Duration
caching bool
}

// Option overrides behavior of Connect.
type Option interface {
apply(*options)
}

type optionFunc func(*options)

func (f optionFunc) apply(o *options) {
f(o)
}

func WithTimeout(t time.Duration) Option {
return optionFunc(func(o *options) {
o.timeout = t
})
}

func WithCaching(cache bool) Option {
return optionFunc(func(o *options) {
o.caching = cache
})
}

// Connect creates a connection.
func Connect(
addr string,
opts …Option,
) (*Connection, error) {
options := options{
timeout: defaultTimeout,
caching: defaultCaching,
}

for _, o := range opts {
o.apply(&options)
}

// …
}

// Options must be provided only if needed.

db.Connect(addr)
db.Connect(addr, db.WithTimeout(newTimeout))
db.Connect(addr, db.WithCaching(false))
db.Connect(
addr,
db.WithCaching(false),
db.WithTimeout(newTimeout),
)
See also,
Self-referential functions and the design of options
Functional options for friendly APIs

You may also like

Leave a Comment