Go Idioms as Patterns

Same story, different language

If you come from JavaScript, your first Go code will probably work but look odd to a Go reviewer. You'll write a big interface next to every struct, try to fake inheritance, or wonder where try/catch went. That code isn't wrong — it's just not idiomaticIdiomThe usual, natural way to express something in a particular language. Code can be correct but un-idiomatic — it works, yet reads like a translation from another language..

What's missing, and what replaces it

The design patternsDesign patternA named, reusable shape for solving a common design problem — like “wrap it so it fits” (adapter). It's a vocabulary, not a library: you write the code yourself each time. you may have read about (factory, strategy, decorator…) were mostly described for languages with classes. Go gets the same results with a smaller toolbox. Here's the whole page on one table:

Every row on the right is simpler than the one on the left, and that's on purpose. Go was designed for big teams reading each other's code. So it prefers one obvious way that is a bit more verbose over clever tricks that hide what's happening.

Five sentences to remember

These are adapted from the Go Proverbs, a short talk by Rob Pike, one of Go's designers. The rest of the page explains each one.

Interfaces you never declare you implement

An InterfaceInterfaceA list of method names (and their signatures) with no code. Any type that has those methods can be used wherever the interface is expected. In Go this happens automatically, without writing “implements”. is a list of method signatures. Here's one of the most-used interfaces in Go, from the standard library's fmt package:

type Stringer interface {
    String() string
}

Any type with a String() string method is a Stringer. You don't register it anywhere. fmt.Println checks for it and, if present, uses it to print your value:

type Temp float64                       // a new type based on float64

func (t Temp) String() string {         // ← this method is all it takes
    return fmt.Sprintf("%.1f°C", float64(t))
}

func main() {
    fmt.Println(Temp(21.5))             // 21.5°C  — Println found String()
}

The same idea in JavaScript

JavaScript has no interfaces at all. It uses Duck typingDuck typing“If it walks like a duck and quacks like a duck, it's a duck”: code accepts any object that has the methods it calls, without checking its class. This is how plain JavaScript works.: call the method and hope it's there. TypeScript adds interfaces that are also matched by shape. Go is the same idea, checked at compile time:

type Stringer interface{ String() string }

type User struct{ Name string }
func (u User) String() string { return "user " + u.Name }

func show(s Stringer) { fmt.Println(s.String()) }

show(User{Name: "ann"}) // ✅ compiles: User has String()
show(42)                // ❌ compile error: int does not implement Stringer

The Go version gives you the flexibility of duck typing — any type can join, even one written years before the interface existed — plus the safety of a compiler check. This combination is called an Implicit interfaceImplicit interfaceAn interface that a type satisfies just by having the right methods — no “implements” keyword. Go's interfaces all work this way., and it's what makes the next section's idiom possible.

Small interfaces are the strong ones

The most powerful interfaces in Go have one method. The two below are used by files, network connections, HTTP bodies, gzip, hashing, buffers and hundreds of other types:

type Reader interface {
    Read(p []byte) (n int, err error)   // fill p with up to len(p) bytes
}
type Writer interface {
    Write(p []byte) (n int, err error)  // write the bytes in p somewhere
}

Because io.Copy(dst Writer, src Reader) asks for only these two tiny behaviours, it can copy a file to a network connection, an HTTP body into a gzip writer, or a string into a hash — combinations its authors never imagined. The fewer methods an interface demands, the more types can satisfy it, and the more places it's useful.

Bigger interfaces are built by embedding small ones

When you need both, you combine them. Listing one interface inside another is called interface embedding: the result requires every method of both.

type ReadWriter interface {
    Reader     // all of Reader's methods…
    Writer     // …plus all of Writer's
}

Who qualifies? Method sets and pointer receivers

One rule trips up almost everyone once. A method can have a value receiver, (f File), or a pointer receiver, (f *File), when it needs to change the original. The list of methods a type "has", as far as interfaces care, is its Method setMethod setThe list of methods a type has, as far as interfaces are concerned. A value of type T has only T's value-receiver methods; a *T has both value- and pointer-receiver methods.:

• a *File (pointer) has all of File's methods;
• a plain File value has only the value-receiver ones.

Why? If you store a plain File value in an interface, Go holds a copy of it. A pointer method like Write is meant to change the original — and there's no original address to give it. So Go refuses, instead of silently changing a copy. Try it:

type Temp float64
func (t Temp) String() string { … }         // value receiver

type File struct{ name string }
func (f File) String() string { … }         // value receiver
func (f *File) Read(p []byte) (int, error)  // pointer receiver
func (f *File) Write(p []byte) (int, error) // pointer receiver

Accept interfaces, return structs

A worked example

A billing package needs to load and save invoices. The database code lives in another package, postgres, whose Store has dozens of methods. Here's the non-idiomatic version, then the idiomatic one:

package billing

import "example.com/app/postgres"

type Service struct {
    store *postgres.Store // needs a real DB
}

func New(s *postgres.Store) *Service {
    return &Service{store: s}
}
// To test Service you now need Postgres
// running, or a fake of ALL Store methods.

package billing

// Only the two methods billing calls.
type invoiceStore interface {
    GetInvoice(ctx context.Context, id string) (Invoice, error)
    SaveInvoice(ctx context.Context, inv Invoice) error
}

type Service struct{ store invoiceStore }

func New(s invoiceStore) *Service { // accept an interface
    return &Service{store: s}       // return a struct
}

Three things happened in the right-hand version:

1. The interface lives with the code that uses it (the consumer), not with the code that implements it. postgres doesn't even know billing exists — implicit interfaces (§02) make that possible.
2. It lists two methods, not forty. Anything with those two methods works: Postgres, an in-memory map, a cache wrapper, a test fake.
3. New returns *Service, a concrete type. Callers get every method and field, can see real docs in their editor, and you can add methods later without breaking anyone.

Try plugging different types into New and see what the compiler says:

Why this makes tests easy

The test can now pass in a tiny fake instead of a database. A fake is one kind of Test doubleTest double (dummy, stub, spy, mock, fake)A stand-in for a real dependency in tests — e.g. a fake payment client that records calls instead of charging a card. Dummy, stub, spy, mock and fake are the common kinds.: a stand-in object that behaves just enough like the real thing.

Here's the Invoice type and the method the test will exercise:

type Invoice struct {
    ID    string
    Total int // in cents
}

// ApplyDiscount loads an invoice, takes `pct` percent off, and saves it.
func (s *Service) ApplyDiscount(ctx context.Context, id string, pct int) error {
    inv, err := s.store.GetInvoice(ctx, id)
    if err != nil {
        return fmt.Errorf("apply discount %s: %w", id, err)
    }
    inv.Total = inv.Total * (100 - pct) / 100
    return s.store.SaveInvoice(ctx, inv)
}

// billing_test.go
type fakeStore struct{ saved []Invoice }

func (f *fakeStore) GetInvoice(ctx context.Context, id string) (Invoice, error) {
    return Invoice{ID: id, Total: 100}, nil
}
func (f *fakeStore) SaveInvoice(ctx context.Context, inv Invoice) error {
    f.saved = append(f.saved, inv) // remember what was saved
    return nil
}

func TestApplyDiscount(t *testing.T) {
    fake := &fakeStore{}
    svc := New(fake) // ✅ *fakeStore satisfies invoiceStore
    _ = svc.ApplyDiscount(context.Background(), "inv-1", 10)
    if got := fake.saved[0].Total; got != 90 {
        t.Fatalf("total = %d, want 90", got)
    }
}

This is DependencyDependencySomething your code needs to do its job — another type, a database client, a logger, a library. If A calls B, A depends on B. injection in its simplest form: the dependency is passed in instead of created inside. Wiring big programs this way has its own topic — see Dependency Injection.

A shortcut for big interfaces you don't own

Sometimes you must accept a big interface from someone else's package — imagine a third-party storage.Bucket interface with 12 methods — and your test only cares about one. A struct field can have an interface type, and you can embed an interface in a struct too (embedding is explained fully in §08; it makes the field's methods callable on the struct). An embedded interface field stays nil until you set it. So embed it in your fake and override just the one method:

type fakeBucket struct {
    storage.Bucket                 // ← embedded interface: "the other 11 methods"
    objects map[string][]byte
}

// Override only what the test uses.
func (f *fakeBucket) Get(ctx context.Context, key string) ([]byte, error) {
    return f.objects[key], nil
}

fakeBucket now satisfies all of storage.Bucket. The embedded field is left as nil, so calling any method you didn't override panics with a nil-pointer error — which in a test is exactly what you want: a loud failure that says "this test touched something unexpected". (How embedding works in general is §08.)

Inside an interface: the nil that isn't nil

That one fact explains Go's most famous gotcha, and it's also how type assertions work. It matters most for error, which is itself an interface (§05).

The two slots

When you write var r io.Reader = file, Go stores two things in r:

• the type slot: the concrete type now inside, here *os.File. This is called the Dynamic typeDynamic typeThe concrete type sitting inside an interface value right now (e.g. *os.File inside an io.Reader). It can change every time you assign a new value., because it can change each time you assign.
• the value slot: the actual data — here, the pointer to the file.

Calling r.Read(buf) looks at the type slot to find which Read method to run, then calls it with the value. This pair is an Interface valueInterface valueWhat a variable of interface type actually holds: two slots — the concrete type stored in it, and the value itself. It's nil only when both slots are empty.. Now watch what happens when the value is a nil pointerPointer (*T, &v)A value that holds the memory address of another value instead of a copy of it. In Go, &v takes v's address and *T is the type “pointer to T”; changes made through a pointer are seen by everyone holding it. JS objects behave like this automatically.:

var err error            // declared, nothing assigned
fmt.Println(err == nil)  // ?

The trap in plain words: a nil pointer is not a nil interface. A *NotFound that is nil still has a type, and putting it into an error writes that type into the type slot. err == nil asks "are both slots empty?", and the answer is no.

Asking what's in the box: type assertions

Because the box remembers the type, you can ask for it back. A Type assertionType assertionx.(T) in Go: “I believe the interface x holds a T — give it to me”. With the comma-ok form, v, ok := x.(T), it reports false instead of panicking when you're wrong. says "I think the interface holds a T; give me the T":

var x any = "hello"          // any = an interface with no methods: holds anything

s := x.(string)              // ✅ s is "hello"
fmt.Println(s)

// n := x.(int)              // 💥 would panic: interface conversion: interface {} is string, not int

n, ok := x.(int)             // ✅ no panic: n is 0, ok is false
if ok {
    fmt.Println("an int:", n)
}

Many possible types: the type switch

When there are several types to handle, a Type switchType switchswitch v := x.(type) { case string: … case int: … } — a switch that branches on the dynamic type inside an interface value. checks the type slot once and branches:

func describe(x any) string {
    switch v := x.(type) {     // ← .(type) only works inside a switch
    case nil:
        return "nothing"       // both slots empty
    case string:
        return "text: " + v    // here v is a string
    case int, int64:
        return fmt.Sprint("number: ", v) // several types: v stays `any`
    case fmt.Stringer:
        return "stringer: " + v.String() // interfaces work as cases too
    default:
        return fmt.Sprintf("other: %T", v) // %T prints the type name
    }
}

Cases are checked top to bottom, so put specific types before broad interfaces. Type switches are handy at edges — decoding JSON, handling several message types. If you find one in the middle of your business logic, a method on an interface is usually cleaner: each type then carries its own behaviour, and adding a new type doesn't mean editing every switch.

Errors are values

The shape of every Go call that can fail

func loadConfig(path string) (Config, error) {
    data, err := os.ReadFile(path)
    if err != nil {                        // ← the most-written line in Go
        return Config{}, err               // hand the problem to our caller
    }
    var cfg Config
    if err := json.Unmarshal(data, &cfg); err != nil {
        return Config{}, err
    }
    return cfg, nil                        // nil error = success
}

Why Go chose this

The diagram shows the difference. An exception jumps over every function in between; a returned error walks back up through each one:

This buys three things:

• You can see every place that can fail. Each if err != nil is visible in the code. In JS, any line inside try might throw, and you can't tell which by reading it.
• Each layer can add context on the way up ("load profile: user 7: not found") — that's §06.
• Errors are just data, so you can store them, put them in a slice, send them on a channel, or compare them, like any value.

The price is verbosity: if err != nil { return …, err } appears constantly. Go's designers decided that's worth it.

What is an error?

error is a built-in interface with a single method (§02 said small interfaces are strong — here's the proof):

type error interface {
    Error() string
}

Anything with an Error() string method is an error. There are three common ways to make one, from simplest to richest:

// 1. A one-off message.
err := errors.New("disk full")
err = fmt.Errorf("user %d has no email", id) // Errorf = formatted message

// 2. A sentinel: one exported, pre-made value that callers can check for.
var ErrNotFound = errors.New("not found")    // by convention: named ErrXxx

// 3. A custom type: carries structured data, not just text.
type ValidationError struct {
    Field string
    Issue string
}

func (e *ValidationError) Error() string {
    return e.Field + ": " + e.Issue
}

A Sentinel errorSentinel errorA single, pre-made error value that a package exports so callers can check for it, e.g. io.EOF or sql.ErrNoRows. You compare against it with errors.Is. is like a well-known code: io.EOF ("no more input"), sql.ErrNoRows, fs.ErrNotExist. The caller checks "is it that one?". A Custom error typeCustom error typeYour own type with an Error() string method, so it can carry extra fields (status code, file path, field name). Callers pull it out with errors.As. is for when the caller needs details — which field was invalid, which HTTP status, which file path. §06 shows how to check for both, even after they've been wrapped.

Wrapping, errors.Is and errors.As

A bare not found reaching your HTTP handler is useless: not found where? Each layer knows a little more about what was going on, so each adds a few words. That's Error wrappingError wrappingReturning a new error that adds context (“load profile: …”) while keeping the original error inside it, so code further up can still find the original., and Go does it with one extra letter in fmt.Errorf: %w.

Watch a chain form and get unwrapped

Step through it. Notice that no layer knows what the others wrote — each just adds its own context and passes the error up. Then flip the toggle to %v and replay: the printed message is identical, but the chain is broken:

1var ErrNotFound = errors.New("not found")
2 
3func dbGet(id int) error {
4    return ErrNotFound
5}
6func repoGet(id int) error {
7    if err := dbGet(id); err != nil {
8        return fmt.Errorf("user %d: %w", id, err)
9    }
10    return nil
11}
12func loadProfile(id int) error {
13    if err := repoGet(id); err != nil {
14        return fmt.Errorf("load profile: %w", err)
15    }
16    return nil
17}
18 
19err := loadProfile(7)               // in the HTTP handler
20fmt.Println(err)
21if errors.Is(err, ErrNotFound) { /* 404 */ }

The result is an Error chainError chainThe line of errors you get by wrapping repeatedly: outer → inner → … → the original cause. errors.Is and errors.As walk it from the outside in.. Two functions walk it from the outside in:

errors.As: pulling out a custom type

errors.As is the error version of a type assertion (§04) that also looks through wrapping. You give it a pointer to a variable; if it finds a matching error, it fills that variable in:

_, err := os.Open("/etc/app.yaml")             // assume the file is missing
if err != nil {
    err = fmt.Errorf("load config: %w", err)   // wrapped once
}

var pathErr *fs.PathError                       // the type we're looking for
if errors.As(err, &pathErr) {                   // ← note the &
    fmt.Println("failed path:", pathErr.Path)   // /etc/app.yaml
    fmt.Println("operation:", pathErr.Op)       // open
}
if errors.Is(err, fs.ErrNotExist) {             // also true — see below
    fmt.Println("file is missing")
}

One subtlety: the error inside the PathError is really the operating system's code ENOENT ("no such file"), not fs.ErrNotExist itself. errors.Is still says true, because that OS error type has an Is method declaring "I count as fs.ErrNotExist" (the staff note at the end of this section shows how).

The same thing in JavaScript: Error.cause

Since ES2022 (Node 16.9+), JS errors can carry a cause, which is wrapping by another name. What JS lacks is a built-in errors.Is: you walk the chain yourself.

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

func repoGet(id int) (User, error) {
    u, err := db.Get(id)
    if err != nil {
        return User{}, fmt.Errorf("repo: user %d: %w", id, err)
    }
    return u, nil
}

_, err := repoGet(7)
if errors.Is(err, ErrNotFound) { // walks the whole chain
    // 404
}

Many errors at once: errors.Join

Sometimes several things fail together — validating five form fields, or closing three files. Go 1.20 added errors.Join, which bundles errors into one. errors.Is and errors.As search every branch:

var errs []error
if u.Name == "" {
    errs = append(errs, &ValidationError{Field: "name", Issue: "required"})
}
if !strings.Contains(u.Email, "@") {
    errs = append(errs, &ValidationError{Field: "email", Issue: "invalid"})
}
err := errors.Join(errs...)   // nil if errs is empty — handy!
// err.Error() is the messages joined by newlines:
// name: required
// email: invalid

fmt.Errorf can also wrap more than one error since Go 1.20: fmt.Errorf("sync failed: %w; cleanup failed: %w", err1, err2). JavaScript's nearest equivalent is AggregateErrorAggregateErrorThe error Promise.any fails with when every promise failed. Its .errors property lists each individual failure., whose .errors array holds every failure.

panic and recover: for bugs, not for flow

Go does have something exception-like: panic / recoverpanic / recoverpanic is Go's crash-the-program error (like an uncaught throw). recover, called inside a deferred function, catches it — but only in the same goroutine.. A panic stops the current function, runs its deferred calls, then does the same in its caller, and so on up the Call stackCall stackThe list of functions that are running right now — each one sits on top of the one that called it. When a function returns, its entry (and its local variables) is thrown away. — that's called unwinding the stackStack unwindingExiting function after function back up the call stack — running each one's cleanup (defer, finally) on the way — as a panic or a thrown exception does.. If nothing stops it, the whole program crashes and prints a Stack traceStack traceThe list of function calls that were active when an error or crash happened — “main called handle, which called save, which failed on line 42”..

When panicking is right

The Must pattern from the last row is common in the standard library: a function that returns an error gets a twin that panics instead, meant for values known when you write the code.

// At package level, runs once at program start.
// If the pattern is invalid, crash immediately — it's a typo in our code.
var slugRe = regexp.MustCompile(`^[a-z0-9-]+$`)

// For input from users, use the version that returns an error:
re, err := regexp.Compile(userPattern)
if err != nil {
    return fmt.Errorf("bad pattern: %w", err)
}

recover: catching a panic

recover() stops a panic in progress. It only works inside a deferred function, and only for a panic in the same goroutine:

func safeHandle(w http.ResponseWriter, r *http.Request) {
    defer func() {
        if v := recover(); v != nil {        // v is whatever was passed to panic
            log.Printf("panic: %v\n%s", v, debug.Stack())
            http.Error(w, "internal error", http.StatusInternalServerError)
        }
    }()
    handle(w, r)                             // if this panics, the defer runs
}

Embedding: composition with shortcuts

InheritanceInheritanceMaking a class by extending another one (class Admin extends User), so it gets all the parent's fields and methods. Go doesn't have it on purpose. says "an Admin is a User". Go doesn't have it. Instead it encourages CompositionCompositionBuilding a type out of other types by holding them as fields (“has-a”) instead of inheriting from them (“is-a”). The usual Go and modern-JS style.: "a Service has a Logger". Embedding is just composition with less typing.

From a normal field to an embedded one

type Service struct {
    log Logger         // named field
}

s.log.Log("started")   // always go through .log

type Service struct {
    Logger             // no field name = embedded
}

s.Log("started")       // shortcut for s.Logger.Log
s.Logger.Log("started") // the long form still works

That's Struct embeddingStruct embeddingPutting a type inside a struct without a field name (type Service struct { Logger }). The inner type's fields and methods become usable directly on the outer struct.. The embedded field's name is its type name (Logger), and its methods are promoted: callable on the outer struct as if they were its own. That's Method promotionMethod promotionWith struct embedding, the embedded type's methods can be called directly on the outer struct — s.Log() is shorthand for s.Logger.Log().. Promoted methods also count toward the outer type's method set (§02), so if Logger satisfies some interface, Service does too. (Same pointer rule as §02: pointer-receiver methods of an embedded Logger are promoted only to *Service, not to a plain Service value.)

The surprise: no overriding from the inside

Here's where embedding and inheritance part ways. If the inner type's method calls another method, it calls its own version — even when the outer type has a method with the same name. Click s.Hello(), then switch to JS extends to compare:

type Base struct{}
func (b Base) Name() string  { return "base" }
func (b Base) Hello() string { return "hello from " + b.Name() }
func (b Base) Close() error  { return nil }

type Logger struct{ prefix string }
func (l Logger) Log(msg string) { fmt.Println(l.prefix + msg) }
func (l Logger) Close() error   { return nil }

type Service struct {
    Base                         // embedded: no field name
    Logger                       // embedded
}
func (s Service) Name() string { return "service" }

s := Service{Logger: Logger{prefix: "[svc] "}}

Why "hello from base"? Go rewrites s.Hello() as s.Base.Hello(). Inside Hello, the receiver b is the Base value sitting inside s — just a Base, with no link back to the Service around it. So b.Name() can only mean Base.Name.

In a JS class, this is the whole object, so a parent method calling this.name() reaches the child's override. That's called Virtual dispatchVirtual dispatch (dynamic dispatch)Choosing which version of a method to run based on the real type of the object at run time. In a JS class, this.name() inside a parent method calls the child's override because of it., and it's what makes "override one step of the parent's algorithm" designs work. Go structs don't have it.

Getting "override" behaviour the Go way

If you need the inner code to call something customizable, make that part an interface (or a function) field and pass it in. The behaviour is then chosen explicitly, instead of by a hidden parent-child link:

type Namer interface{ Name() string }

type Greeter struct {
    namer Namer                  // the customizable part, passed in
}

func (g Greeter) Hello() string {
    return "hello from " + g.namer.Name() // calls whatever was given
}

type Service struct{}
func (Service) Name() string { return "service" }

g := Greeter{namer: Service{}}
fmt.Println(g.Hello())           // hello from service ✓

This is the strategy pattern in a nutshell — Behavioral patterns covers it properly. Wrapping a value to add behaviour around it (decorators, HTTP middleware) is in Structural patterns.

Embedding exports everything — including what you didn't mean to

Promotion is all-or-nothing: every exported method of the embedded type becomes part of the outer type's public API. The classic accident is embedding a mutexLock (mutex)A “do not disturb” sign for a piece of data: only the task holding the lock may touch it; others wait their turn.:

type Cache struct {
    sync.Mutex                 // promotes Lock() and Unlock()
    items map[string]string
}

// Any caller can now do this:
c.Lock()   // …and forget to Unlock → every Get hangs

type Cache struct {
    mu    sync.Mutex           // private: only Cache's methods use it
    items map[string]string
}

func (c *Cache) Get(k string) string {
    c.mu.Lock()
    defer c.mu.Unlock()
    return c.items[k]
}

Callers can now lock your cache from outside, and you can never remove that ability without breaking them. Keep the mutex as a named, lowercase field. (Mutexes themselves are covered in Locks.) The same reasoning applies to embedding anything with a big API, like *sql.DB or http.Client: you're publishing all of it.

Everyday idioms: zero values, comma-ok, defer, generics

Make the zero value useful

Every Go variable starts with a Zero valueZero valueThe default value of a Go type: 0 for numbers, "" for strings, false for bools, nil for pointers, slices, maps and channels.: 0, "", false, nil, or a struct with all fields at their zero values. Well-designed types are ready to use in that state, so callers don't need a constructor:

var buf bytes.Buffer           // no New… call needed
buf.WriteString("hello")       // works immediately

var mu sync.Mutex              // an unlocked mutex
var wg sync.WaitGroup          // a counter at 0

type Counter struct {
    hits map[string]int        // ⚠️ zero value is a nil map
}
func (c *Counter) Add(k string) {
    if c.hits == nil {         // ← make the zero value work
        c.hits = make(map[string]int)
    }
    c.hits[k]++
}
var c Counter
c.Add("home")                  // ✅ no constructor required

Constructors only when you need them

Go has no constructor keyword. When a type can't have a useful zero value — it needs a required dependency, or must validate input — write a plain function named NewX (a ConstructorConstructorThe code that builds a new, ready-to-use object. In JS it's the constructor() method of a class; in Go it's a plain function named by convention NewThing(…).):

func NewServer(addr string, store invoiceStore) (*Server, error) {
    if addr == "" {
        return nil, errors.New("server: addr is required")
    }
    return &Server{addr: addr, store: store, timeout: 30 * time.Second}, nil
}

Return an error if construction can fail. If a constructor grows many optional settings, the idiomatic answer is functional options — covered in Creational patterns.

The comma-ok idiom

Go doesn't use special "not found" values like undefined or -1. When an operation might come up empty, it can return a second boolean — the Comma-ok idiomComma-ok idiomGo's pattern of returning a second boolean that says whether the first value is real: v, ok := m[key], v, ok := <-ch, v, ok := x.(T). form you met with type assertions in §04. Here are all three places it appears:

ages := map[string]int{"ann": 0}

age, ok := ages["bob"]          // map lookup
if !ok {
    fmt.Println("no bob")       // without ok, you'd get 0 and couldn't tell
}

s, ok := value.(fmt.Stringer)   // type assertion (§04): no panic if wrong

msg, ok := <-ch                 // channel receive: ok is false once ch is closed

The map case is the one that bites: ages["ann"] and ages["bob"] both return 0, but only one of them is in the map. (For channels, see Channels §02.)

defer: clean up right where you open

Put the cleanup on the line right after acquiring the resource. defer runs it when the function returns, however it returns — normal return, early return err, or panic:

func countLines(path string) (int, error) {
    f, err := os.Open(path)
    if err != nil {
        return 0, err
    }
    defer f.Close()               // ← paired with Open, can't be forgotten

    n := 0
    sc := bufio.NewScanner(f)
    for sc.Scan() {
        n++
    }
    return n, sc.Err()            // f.Close() runs after this
}

Deferred calls run in reverse order (last deferred, first run), like stacking plates. Avoid defer inside a long loop: nothing runs until the function returns, so 10,000 opened files would stay open until the end.

Generics or interfaces?

Since Go 1.18, functions and types can take type parametersType parameter (generics)A placeholder for a type, written in square brackets in Go: func Max[T cmp.Ordered](a, b T) T works for ints, floats or strings. The compiler fills in T at each call. Added in Go 1.18., written in square brackets. Each one has a Type constraintType constraintIn Go generics, the rule a type parameter must satisfy, written like an interface: [T any], [T comparable], or [T int | float64]. saying which types are allowed:

// Works for a slice of ANY element type, keeps the type in the result.
func Filter[T any](xs []T, keep func(T) bool) []T {
    var out []T
    for _, x := range xs {
        if keep(x) {
            out = append(out, x)
        }
    }
    return out
}

evens := Filter([]int{1, 2, 3, 4}, func(n int) bool { return n%2 == 0 }) // []int{2, 4}

// A constraint listing allowed types:
type Number interface{ ~int | ~int64 | ~float64 }

func Sum[T Number](xs []T) T {
    var total T                    // zero value of T
    for _, x := range xs {
        total += x                 // + is allowed: every type in Number supports it
    }
    return total
}

The rule of thumb:

If you write a generic function whose body only calls methods on T, it probably just wants an interface parameter. And if you're unsure, start without generics — the standard library's slices and maps packages already cover most needs.

Package design and naming

A Package / modulePackage / moduleA folder (Go) or file (JS) of code with its own namespace. Other code imports it and can only use what it exports — capitalized names in Go, export in JS. in Go is one folder of .go files. Code outside the package uses it as pkgname.Thing, and can only see names that start with a capital letter. Those two facts drive most Go naming rules.

Don't stutter

Because callers always write the package name, repeating it in the type name says everything twice:

package http

type HTTPServer struct{ … }
type HTTPRequest struct{ … }

// caller:  http.HTTPServer, http.HTTPRequest

package http

type Server struct{ … }
type Request struct{ … }

// caller:  http.Server, http.Request
// (what the standard library does)

Same for functions: when a package has one main type, its constructor is just New — list.New(), template.New(name) — so you'd write user.New(), not user.NewUser(). And it's bytes.Buffer, not bytes.ByteBuffer.

Name packages for what they provide

When a function in util is used by one package, move it there. If several packages need it, it deserves a real package with a real name — strings, not stringutil.

internal/: code that can't leak

Any package under a folder named internal can only be imported by code inside the parent of that folder. The compiler enforces it:

myapp/
├── cmd/server/main.go       # can import myapp/internal/...
├── billing/billing.go       # can import myapp/internal/...
└── internal/
    └── pgstore/store.go     # other modules can't import this

Here a moduleGo moduleA versioned set of Go packages defined by a go.mod file — roughly what an npm package is in JavaScript. Other projects import your module by its path, e.g. github.com/you/app. means a whole Go project with its own go.mod file, roughly an npm package. An internal/ packageinternal/ packageA Go package inside a folder named internal. The compiler only lets code from the parent folder's tree import it, so it can't become part of your public API by accident. lets you split code into packages for your own clarity without promising anything to the outside world. Anything exported outside internal/ becomes your public APIAPIApplication Programming Interface: the set of functions, types or HTTP endpoints that one piece of software offers for others to call., and other modules may start depending on it.

Short names in small scopes

Go prefers short names when the meaning is obvious from nearby code:

• Receivers: one or two letters from the type name, and the same everywhere — func (s *Server) Start(), never this or self.
• Loop and local variables: i, r (request), w (writer), ctx, err.
• Exported names used far away get full words: ReadTimeout, ErrNotFound.
• Acronyms keep one case: ServeHTTP, userID, parseURL — not ServeHttp, userId.
• No Get prefix on getters: u.Name(), and u.SetName(…) for the setter.

Staff-level: idioms at scale

1 · Interface pollution

Interface pollutionInterface pollutionDeclaring interfaces that nobody needs — one per struct, “just in case”. It adds indirection and names without adding any flexibility. is the habit of declaring an interface for every struct "for testability" or "for flexibility". In Go it costs more than it buys:

• Navigation breaks. "Go to definition" lands on an interface, not code. Every reader pays an extra hop, forever.
• The interface fossilizes. Once five packages use a 20-method UserService interface, splitting it is a big refactor — and every fake must implement all 20.
• It solves nothing. Thanks to implicit interfaces (§02), a consumer can declare the 2-method interface it needs later, when a second implementation or a test actually appears.

Don't design with interfaces, discover them.— Rob Pike

The healthy pattern is the one from §03: concrete types in the producer, small interfaces in each consumer, discovered when a real need shows up.

2 · Returning interfaces (and when it's right)

Returning an interface from a constructor hides the concrete type. That has three costs: callers can't reach extra methods or fields without a type assertion; adding a method to that interface later breaks anyone who implemented it; and §04's nil-pointer-in-interface trap becomes possible on every return path.

It is right when the concrete type is truly an implementation detail and several implementations exist behind one constructor — errors.New returns error, sha256.New returns hash.Hash, io.MultiReader returns io.Reader. Notice these are all tiny, stable interfaces from the standard library.

3 · Errors at boundaries: context once, log once, translate at the edge

Three rules keep error handling sane in large codebases:

Add context, not duplication. Each layer adds what it was doing and the key identifiers: "charge invoice %s: %w". Don't repeat the inner message, and don't start with "failed to" or "error:" — in a chain of five, those words become noise.

Log once, at the top. The layer that finally handles the error — the HTTP handler, the job runner, main — logs it, with the full wrapped message. Layers that return it don't log. Otherwise one failure shows up as five log lines that look like five failures.

Translate at package boundaries. Wrapping with %w makes the inner error part of your APIAPIApplication Programming Interface: the set of functions, types or HTTP endpoints that one piece of software offers for others to call.: callers can now errors.Is(err, sql.ErrNoRows) against your package, and you can never switch away from SQL without breaking them. At the boundary, convert to your own vocabulary:

var ErrNotFound = errors.New("user: not found") // our sentinel, our promise

func (s *Store) Get(ctx context.Context, id string) (*User, error) {
    u, err := s.queryUser(ctx, id)
    if errors.Is(err, sql.ErrNoRows) {
        return nil, ErrNotFound                       // translate: hide the DB detail
    }
    if err != nil {
        return nil, fmt.Errorf("user: get %s: %v", id, err) // %v: message kept, type hidden
    }
    return u, nil
}

Keep stack traces where you need them. Go errors carry no Stack traceStack traceThe list of function calls that were active when an error or crash happened — “main called handle, which called save, which failed on line 42”. by default. A good wrapped message usually tells you more than a trace would. If you need traces (say, for an error tracker), add them in one place — a custom error type created at the boundary — rather than at every layer.

4 · Errors in concurrent code

A goroutine can't return an error to whoever started it; errors must be sent back (over a channel), or collected with errgroup, which returns the first error and — when created with errgroup.WithContext and the goroutines respect ctx — cancels the others. Both are taught in Async / Await §11 and §12. Two idiom-level notes on top:

• When you want every failure, not just the first, collect them in a slice and return errors.Join(errs...) (§06). Guard the slice with a mutex, or have each goroutine write to its own index.
• Treat context.Canceled and context.DeadlineExceeded (check with errors.Is) as "we stopped on purpose", not as failures to alert on.

5 · API stability: what you can change later

Once other teams import your package, some changes are free and some are a Breaking changeBreaking changeA change to a package's public API that makes existing code using it stop compiling or behave differently — e.g. adding a method to an exported interface.:

This is one more reason for "return structs, accept small interfaces": structs can grow safely, while exported interfaces are frozen the day you publish them. Go's own standard library honours this with the Go 1 compatibility promise — almost all code written for Go 1.0 in 2012 still compiles today.

Pitfalls

var err error
if cond {
    result, err := compute()   // ← NEW err, only inside this block
    if err != nil {
        log.Println("compute:", err)
    }
    use(result)
}
return err                     // always nil: the outer err never changed

1func run(cond bool) error {
2    var err error
3    if cond {
4        result, err := compute()  // := → a NEW err
5        if err != nil {
6            log.Println("compute:", err)
7        }
8        use(result)
9    }
10    return err
11}

Check yourself: predict the output

Commit to an answer before you click. If you miss one, go back to the widget in that section — the interface box (§04), the error chain (§06), or the method explorer (§08) — and replay it with the puzzle in mind.

type MyErr struct{}
func (*MyErr) Error() string { return "boom" }

func check() error {
    var e *MyErr
    return e
}

func main() {
    err := check()
    fmt.Println(err == nil)
}

base := errors.New("timeout")
a := fmt.Errorf("fetch: %w", base)
b := fmt.Errorf("fetch: %v", base)
fmt.Println(errors.Is(a, base), errors.Is(b, base))

type Animal struct{}
func (Animal) Name() string  { return "animal" }
func (a Animal) Intro() string { return "I am " + a.Name() }

type Dog struct{ Animal }
func (Dog) Name() string { return "dog" }

fmt.Println(Dog{}.Name(), "/", Dog{}.Intro())

type Counter struct{ n int }
func (c *Counter) Inc() { c.n++ }

type Incrementer interface{ Inc() }

var x Incrementer = Counter{}

ages := map[string]int{"ann": 0}
a, okA := ages["ann"]
b, okB := ages["bob"]
fmt.Println(a, okA, b, okB)

_, err := os.Open("/missing.txt")
err = fmt.Errorf("load config: %w", err)

var pe *fs.PathError
fmt.Println(errors.Is(err, fs.ErrNotExist), errors.As(err, &pe))

Cheat sheet