Go Syntax Guide - Kehao Zheng's Website

This guide teaches you Go syntax through simple, self-contained examples. Every concept is illustrated with small programs you could type and run yourself. By the end, you will be able to read any .go file and understand what it does.

What you’ll encounter when reading a `.go` file#

When you open any .go file, you’ll see constructs roughly in this order:

A package declaration — which module this file belongs to
An import block — dependencies from the standard library and other packages
Constants and variables — package-level values (const, var)
Type definitions — structs, interfaces, and custom types
Functions and methods — standalone functions and methods attached to types

This guide covers each construct, then builds up to larger patterns: error handling, collections, control flow, concurrency, and testing. A quick reference table at the end serves as a cheat sheet while you read code.

1. Project Structure and Imports#

`package main` and the entry point#

Every Go program starts at func main() inside a file that declares package main. Here is the simplest Go program:

1
package main
2

3
import "fmt"
4

5
func main() {
6
    fmt.Println("Hello, world!")
7
}

package main tells the compiler this is an executable (not a library).
func main() takes no arguments and returns nothing — it is the starting point of the program.
fmt.Println(...) prints a line to the terminal. fmt is Go’s formatting package.

How Go organizes code#

Every .go file starts with a package declaration. A package is a directory of .go files that are compiled together — similar to a module or namespace in other languages.

1
package math

1
package store

All files in the same directory must declare the same package name. You reference code from another package by importing it.

The module file: `go.mod`#

At the root of your project, go.mod defines the module path and dependencies. It serves a similar role to package.json (Node.js) or requirements.txt (Python).

1
module github.com/yourname/myproject
2

3
go 1.21

module github.com/yourname/myproject — this is the base import path. Every package in this project is imported relative to this path.
go 1.21 — minimum Go version required.

Import blocks#

Imports are grouped in parentheses. By convention, standard library imports come first, then external packages:

1
import (
2
    "fmt"          // standard library — printing
3
    "math/rand"    // standard library — random numbers
4
    "strings"      // standard library — string utilities
5

6
    "github.com/yourname/myproject/store"    // your own package
7

8
    log "github.com/sirupsen/logrus"         // aliased import
9
)

"fmt" — imports the fmt package. You use it as fmt.Println(...).
"github.com/yourname/myproject/store" — imports your store package. You use it as store.AddItem(...).
log "github.com/sirupsen/logrus" — imports a package under the alias log, so you write log.Info(...) instead of logrus.Info(...). This avoids name collisions or provides a shorter name.

Exported vs unexported: the capitalization rule#

Go has no public/private keywords. Instead, the first letter of a name determines visibility:

Uppercase = exported (accessible from other packages): Add, UserName, MaxRetries
Lowercase = unexported (only accessible within the same package): helper, count, defaultTimeout

1
package store
2

3
const MaxItems = 100       // Exported — other packages can use store.MaxItems
4

5
var itemCount int          // unexported — only used inside package store
6

7
func AddItem(name string) { ... }    // Exported
8
func validate(name string) { ... }   // unexported

This is enforced by the compiler: if you try to use store.itemCount from another package, it won’t compile.

2. Variables and Types#

Type definitions#

Go lets you create new named types. This gives you type safety and the ability to attach methods:

1
type Celsius float64       // temperature in Celsius
2
type Fahrenheit float64    // temperature in Fahrenheit
3
type UserID int64          // a unique user identifier

type Celsius float64 creates a new type called Celsius that is backed by a float64. It is not an alias — Celsius and float64 are distinct types. You can attach methods to Celsius but not to float64.
You cannot accidentally pass a Fahrenheit where a Celsius is expected — the compiler catches this.

Variable declarations: `var`#

var declares a variable with an explicit type. It can appear at the package level or inside a function.

1
var name string = "Alice"
2
var age int                   // zero value: 0
3
var isActive bool             // zero value: false

Package-level variables are often grouped in a var (...) block:

1
var (
2
    maxRetries  = 3
3
    defaultName = "Guest"
4
    timeout     = 30   // seconds
5
)

Short variable declaration: `:=`#

Inside a function, := declares and initializes a variable in one step. The type is inferred from the right side.

1
func greet() {
2
    message := "Hello!"           // message is a string
3
    count := 42                   // count is an int
4
    price := 19.99                // price is a float64
5
    data, err := loadFile()       // declare two variables at once
6
    _ = err                       // _ discards a value you don't need
7
}

:= can only be used inside functions, never at package level.
The _ (blank identifier) explicitly discards a value you don’t need.

Constants and `iota`#

const declares compile-time constants. They cannot be changed after declaration:

1
const Pi = 3.14159
2
const MaxUsers = 1000

When you need a sequence of related constants (like an enum), iota auto-generates the values. It starts at 0 and increments by 1 for each line in the const block:

1
type Direction int
2

3
const (
4
    North Direction = iota   // North = 0
5
    East                     // East = 1
6
    South                    // South = 2
7
    West                     // West = 3
8
)

Direction is a custom type based on int. Giving constants a named type makes the code self-documenting and catches misuse at compile time.
East inherits both the type and the iota pattern from the first line — you don’t need to repeat Direction = iota.

Another example — days of the week:

1
type Weekday int
2

3
const (
4
    Monday    Weekday = iota + 1   // Monday = 1
5
    Tuesday                         // Tuesday = 2
6
    Wednesday                       // Wednesday = 3
7
    Thursday                        // Thursday = 4
8
    Friday                          // Friday = 5
9
    Saturday                        // Saturday = 6
10
    Sunday                          // Sunday = 7
11
)

Zero values#

In Go, every variable has a default value if not explicitly initialized. These are called zero values:

Type	Zero value
`int`, `uint64`, etc.	`0`
`float64`	`0.0`
`bool`	`false`
`string`	`""`
pointer, slice, map, channel, interface	`nil`
struct	each field is its zero value

This is used frequently in Go code. For example:

1
var count int       // count is 0
2
var name string     // name is ""
3
var active bool     // active is false
4

5
if name == "" {
6
    fmt.Println("No name set")
7
}

For value types (integers, strings, structs, arrays), Go uses zero values instead of null. Reference types (pointers, slices, maps, channels, interfaces) can be nil — see Pointers: Nil checks.

Type conversions#

Go has no implicit type conversions. You must be explicit:

1
var i int = 42
2
var f float64 = float64(i)       // int → float64
3
var u uint = uint(f)             // float64 → uint
4

5
length := len("hello")           // len() returns int
6
size := int64(length)            // int → int64

If types are incompatible (like string to int), you use standard library functions:

1
import "strconv"
2

3
num, err := strconv.Atoi("123")          // string → int
4
text := strconv.Itoa(42)                  // int → string

3. Functions#

Basic function syntax#

A Go function has: the func keyword, a name, parameters, optional return types, and a body:

1
func add(a int, b int) int {
2
    return a + b
3
}
4

5
func greet(name string) string {
6
    return "Hello, " + name + "!"
7
}

func add — the func keyword followed by the function name.
(a int, b int) — two parameters, both integers.
int after the closing paren — the return type.

When consecutive parameters share a type, you can shorten:

1
func add(a, b int) int {       // a and b are both int
2
    return a + b
3
}

Multiple return values#

Go functions routinely return multiple values. The most common pattern is (result, error):

1
func divide(a, b float64) (float64, error) {
2
    if b == 0 {
3
        return 0, fmt.Errorf("cannot divide by zero")
4
    }
5
    return a / b, nil
6
}

The function returns two values: a float64 result and an error.
On success, the error is nil. On failure, the result is the zero value (0) and the error describes what went wrong.

The caller must handle both values:

1
result, err := divide(10, 3)
2
if err != nil {
3
    fmt.Println("Error:", err)
4
    return
5
}
6
fmt.Println("Result:", result)

Named return values#

Return values can be named, which pre-declares them as local variables initialized to their zero values:

1
func split(total int) (half, remainder int) {
2
    half = total / 2
3
    remainder = total % 2
4
    return    // "naked return" — returns half and remainder implicitly
5
}

(half, remainder int) declares two return variables.
The bare return at the end returns whatever half and remainder currently hold.
Named returns are useful for documentation, but can reduce clarity in longer functions.

Variadic functions (`...`)#

A variadic function accepts any number of arguments of a given type:

1
func sum(numbers ...int) int {
2
    total := 0
3
    for _, n := range numbers {
4
        total += n
5
    }
6
    return total
7
}

numbers ...int means “zero or more int arguments.” Inside the function, numbers is a []int (a slice).
Called like: sum(1, 2, 3) or sum(1, 2, 3, 4, 5) or even sum().

You can also expand a slice into variadic args:

1
nums := []int{1, 2, 3, 4}
2
total := sum(nums...)          // expand slice into individual args

Functions as values and closures#

Functions are first-class values in Go. You can assign them to variables, pass them as arguments, and return them:

1
func main() {
2
    // Assign a function to a variable
3
    double := func(x int) int {
4
        return x * 2
5
    }
6

7
    fmt.Println(double(5))    // prints 10
8

9
    // Pass a function as an argument
10
    result := apply(3, double)
11
    fmt.Println(result)       // prints 6
12
}
13

14
func apply(x int, fn func(int) int) int {
15
    return fn(x)
16
}

Functions that reference variables from their surrounding scope are closures:

1
func makeCounter() func() int {
2
    count := 0
3
    return func() int {
4
        count++           // captures 'count' from outer function
5
        return count
6
    }
7
}
8

9
func main() {
10
    counter := makeCounter()
11
    fmt.Println(counter())    // 1
12
    fmt.Println(counter())    // 2
13
    fmt.Println(counter())    // 3
14
}

The inner function captures count — each call increments the same variable.
makeCounter() returns a function value, and each call to makeCounter() creates a fresh count.

4. Structs and Methods#

Struct definitions#

A struct is a collection of named fields — Go’s equivalent of a class (without inheritance):

1
type Person struct {
2
    Name string
3
    Age  int
4
    Email string
5
}
6

7
type BankAccount struct {
8
    Owner   string
9
    Balance float64
10
    Active  bool
11
}

Each field has a name and a type.
Fields are accessed with dot notation: person.Name, account.Balance.

Creating struct values:

1
// Named fields (preferred — order doesn't matter, self-documenting)
2
alice := Person{
3
    Name:  "Alice",
4
    Age:   30,
5
    Email: "alice@example.com",
6
}
7

8
// Positional (fragile — breaks if you add a field later)
9
bob := Person{"Bob", 25, "bob@example.com"}
10

11
// Partial initialization — omitted fields get zero values
12
guest := Person{Name: "Guest"}   // Age = 0, Email = ""

Struct tags#

Struct fields can have tags — metadata strings in backticks. These are used by encoding libraries:

1
type User struct {
2
    ID        int    `json:"id"`
3
    FirstName string `json:"first_name"`
4
    Password  string `json:"-"`              // excluded from JSON
5
}

json:"first_name" tells the JSON encoder to use "first_name" as the key instead of "FirstName".
json:"-" means this field is never included in JSON output.

Methods: pointer receivers vs value receivers#

Methods are functions attached to a type via a receiver. There are two kinds:

Value receiver — gets a copy of the struct. Used when the method doesn’t modify the struct:

1
func (p Person) FullInfo() string {
2
    return fmt.Sprintf("%s (age %d)", p.Name, p.Age)
3
}

(p Person) — p is a copy. Changes to p wouldn’t affect the original.
Call it: alice.FullInfo().

Pointer receiver — gets a pointer to the struct. Used when the method modifies the struct:

1
func (a *BankAccount) Deposit(amount float64) {
2
    a.Balance += amount
3
}
4

5
func (a *BankAccount) Withdraw(amount float64) error {
6
    if amount > a.Balance {
7
        return fmt.Errorf("insufficient funds")
8
    }
9
    a.Balance -= amount
10
    return nil
11
}

(a *BankAccount) — a is a pointer. Deposit modifies the original BankAccount in place.
Rule of thumb: if a method needs to mutate the receiver, use a pointer receiver. If it’s read-only and the type is small, either works, but pointer receivers are conventional for consistency.

Embedded structs (composition over inheritance)#

Go has no inheritance. Instead, you embed one struct inside another:

1
type Address struct {
2
    Street string
3
    City   string
4
    Zip    string
5
}
6

7
type Employee struct {
8
    Person           // embedded — no field name, just the type
9
    Address          // embedded
10
    Department string
11
}

Person and Address are embedded without field names. This means all of their fields are promoted to Employee.
You can write emp.Name instead of emp.Person.Name, and emp.City instead of emp.Address.City.
This is Go’s version of composition. Employee has a Person and has an Address.

Constructor functions: the `NewXxx` pattern#

Go has no constructors. By convention, you write a function called NewXxx that returns a pointer to an initialized struct:

1
func NewBankAccount(owner string, initialDeposit float64) *BankAccount {
2
    return &BankAccount{
3
        Owner:   owner,
4
        Balance: initialDeposit,
5
        Active:  true,
6
    }
7
}

&BankAccount{...} creates a struct literal and takes its address — returns a pointer.
This is the standard Go pattern for initialization that needs validation or default values.

Another way to allocate:

1
account := new(BankAccount)   // allocates zeroed memory, returns *BankAccount
2
account.Owner = "Charlie"
3
account.Active = true

new(BankAccount) allocates and returns a pointer. All fields start at their zero values.
The &Type{...} form is preferred when you want to set fields immediately.

5. Interfaces#

Interface definitions#

An interface defines a set of method signatures. Any type that implements those methods satisfies the interface — no explicit declaration required.

1
type Shape interface {
2
    Area() float64
3
    Perimeter() float64
4
}

Any struct with Area() float64 and Perimeter() float64 methods automatically satisfies Shape. There’s no implements keyword.

Implicit interface satisfaction#

Let’s define two shapes that both satisfy Shape:

1
type Circle struct {
2
    Radius float64
3
}
4

5
func (c Circle) Area() float64 {
6
    return 3.14159 * c.Radius * c.Radius
7
}
8

9
func (c Circle) Perimeter() float64 {
10
    return 2 * 3.14159 * c.Radius
11
}
12

13
type Rectangle struct {
14
    Width, Height float64
15
}
16

17
func (r Rectangle) Area() float64 {
18
    return r.Width * r.Height
19
}
20

21
func (r Rectangle) Perimeter() float64 {
22
    return 2 * (r.Width + r.Height)
23
}

Now you can use either type wherever a Shape is expected:

1
func printShapeInfo(s Shape) {
2
    fmt.Printf("Area: %.2f, Perimeter: %.2f\n", s.Area(), s.Perimeter())
3
}
4

5
func main() {
6
    c := Circle{Radius: 5}
7
    r := Rectangle{Width: 3, Height: 4}
8

9
    printShapeInfo(c)    // works — Circle satisfies Shape
10
    printShapeInfo(r)    // works — Rectangle satisfies Shape
11
}

The empty interface: `interface{}`#

interface{} has zero methods, so every type satisfies it. It’s Go’s way of saying “any type”:

1
func printAnything(value interface{}) {
2
    fmt.Println(value)
3
}
4

5
func main() {
6
    printAnything(42)
7
    printAnything("hello")
8
    printAnything(true)
9
    printAnything([]int{1, 2, 3})
10
}

Since Go 1.18, any is an alias for interface{} — you’ll see both in code:

1
func printAnything(value any) {    // same as interface{}
2
    fmt.Println(value)
3
}

Type assertions#

When you have a value of interface type and need the concrete type, use a type assertion:

1
var s Shape = Circle{Radius: 5}
2

3
// One-value form — panics if wrong
4
c := s.(Circle)
5
fmt.Println(c.Radius)    // 5
6

7
// Two-value form — safe, returns ok=false if wrong
8
c, ok := s.(Circle)
9
if ok {
10
    fmt.Println("It's a circle with radius", c.Radius)
11
} else {
12
    fmt.Println("Not a circle")
13
}

.( Circle) asserts that s is actually a Circle.
The two-value form c, ok := s.(Circle) is safer — ok is false if the assertion fails.

Type switches#

A type switch branches based on the concrete type of an interface value:

1
func describe(s Shape) string {
2
    switch shape := s.(type) {
3
    case Circle:
4
        return fmt.Sprintf("Circle with radius %.1f", shape.Radius)
5
    case Rectangle:
6
        return fmt.Sprintf("Rectangle %0.1f x %.1f", shape.Width, shape.Height)
7
    default:
8
        return "Unknown shape"
9
    }
10
}

s.(type) can only be used in a switch statement.
Each case binds shape to the concrete type, so you get type-safe access to its fields.

Interface embedding#

Interfaces can embed other interfaces to compose them:

1
type Reader interface {
2
    Read(p []byte) (n int, err error)
3
}
4

5
type Writer interface {
6
    Write(p []byte) (n int, err error)
7
}
8

9
type ReadWriter interface {
10
    Reader     // embedded — includes all Reader methods
11
    Writer     // embedded — includes all Writer methods
12
}

ReadWriter requires all methods of both Reader and Writer. This is how Go builds up larger interfaces from smaller ones — this exact pattern is used in the standard library’s io package.

6. Pointers#

What are pointers?#

A pointer holds the memory address of a value. Go uses * and &:

&x — “address of x” — creates a pointer to x
*p — “value at p” — dereferences a pointer to get the underlying value
*Type in a declaration means “pointer to Type”

Creating pointers#

1
x := 42
2
p := &x              // p is a *int (pointer to int), holds the address of x
3

4
fmt.Println(p)       // prints a memory address like 0xc000012080
5
fmt.Println(*p)      // prints 42 — the value p points to

With structs:

1
// Two ways to create a pointer to a struct:
2
account := &BankAccount{Owner: "Alice", Balance: 100}    // & takes the address
3
account2 := new(BankAccount)                              // new() returns a pointer

Dereferencing#

1
x := 42
2
p := &x
3

4
*p = 100             // change the value at the address p points to
5
fmt.Println(x)       // prints 100 — x was modified through the pointer

With struct fields, Go automatically dereferences pointers — you don’t need (*p).Field:

1
type Point struct{ X, Y int }
2

3
p := &Point{X: 1, Y: 2}
4
p.X = 10             // Go automatically dereferences — same as (*p).X = 10
5
fmt.Println(p.X)     // 10

Nil checks#

Pointers can be nil (they don’t point to anything). Dereferencing a nil pointer panics, so you must check:

1
func printName(p *Person) {
2
    if p == nil {
3
        fmt.Println("No person provided")
4
        return
5
    }
6
    fmt.Println(p.Name)
7
}
8

9
func main() {
10
    var nobody *Person          // nil pointer — points to nothing
11
    printName(nobody)           // prints "No person provided"
12
    printName(&Person{Name: "Alice"})   // prints "Alice"
13
}

Why pointer receivers matter#

A value receiver gets a copy — changes don’t affect the original. A pointer receiver gets the original — changes persist:

1
type Counter struct {
2
    Value int
3
}
4

5
// Value receiver — gets a copy. The increment is LOST.
6
func (c Counter) IncrementBroken() {
7
    c.Value++    // modifies the copy, not the original
8
}
9

10
// Pointer receiver — gets the original. The increment is KEPT.
11
func (c *Counter) Increment() {
12
    c.Value++    // modifies the original
13
}
14

15
func main() {
16
    c := Counter{Value: 0}
17

18
    c.IncrementBroken()
19
    fmt.Println(c.Value)     // still 0!
20

21
    c.Increment()
22
    fmt.Println(c.Value)     // now 1
23
}

7. Error Handling#

The `error` type#

In Go, error is a built-in interface with one method:

1
type error interface {
2
    Error() string
3
}

Any type with an Error() string method is an error. There is no try/catch — errors are returned as values and checked explicitly.

The `if err != nil` pattern#

This is the most common pattern in Go. You’ll see it in almost every function:

1
file, err := os.Open("data.txt")
2
if err != nil {
3
    fmt.Println("Failed to open file:", err)
4
    return
5
}
6
// use file...

The flow is always: call a function, check if err is not nil, handle (usually by returning the error to the caller). This replaces exceptions — the error is propagated explicitly up the call stack.

A chain of operations looks like this:

1
func loadConfig(path string) (*Config, error) {
2
    data, err := os.ReadFile(path)
3
    if err != nil {
4
        return nil, err
5
    }
6

7
    var config Config
8
    err = json.Unmarshal(data, &config)
9
    if err != nil {
10
        return nil, err
11
    }
12

13
    return &config, nil
14
}

Creating errors#

The simplest way to create an error:

1
import "errors"
2

3
var ErrNotFound = errors.New("item not found")
4
var ErrEmpty    = errors.New("list is empty")

For errors with dynamic content, use fmt.Errorf:

1
func withdraw(balance, amount float64) error {
2
    if amount > balance {
3
        return fmt.Errorf("cannot withdraw %.2f: only %.2f available", amount, balance)
4
    }
5
    return nil
6
}

Sentinel errors#

Package-level error variables that callers can compare against:

1
var (
2
    ErrNotFound     = errors.New("not found")           // Exported — part of the API
3
    ErrUnauthorized = errors.New("unauthorized")        // Exported
4
    errInternal     = errors.New("internal error")      // unexported — internal use
5
)
6

7
func findUser(id int) (*User, error) {
8
    if id <= 0 {
9
        return nil, ErrNotFound
10
    }
11
    // ...
12
}

Callers check: if err == ErrNotFound { ... } or the preferred form:

1
if errors.Is(err, ErrNotFound) {
2
    fmt.Println("User does not exist")
3
}

Custom error types#

When you need to carry extra context, define a struct that implements the error interface:

1
type ValidationError struct {
2
    Field   string
3
    Message string
4
}
5

6
func (e *ValidationError) Error() string {
7
    return fmt.Sprintf("validation failed on %s: %s", e.Field, e.Message)
8
}
9

10
func validateAge(age int) error {
11
    if age < 0 {
12
        return &ValidationError{Field: "age", Message: "must be non-negative"}
13
    }
14
    if age > 150 {
15
        return &ValidationError{Field: "age", Message: "unrealistic value"}
16
    }
17
    return nil
18
}

Callers can type-assert to get the extra fields:

1
err := validateAge(-5)
2
var valErr *ValidationError
3
if errors.As(err, &valErr) {
4
    fmt.Printf("Bad field: %s\n", valErr.Field)
5
}

Error wrapping with `%w`#

fmt.Errorf with %w wraps an error, preserving the original for inspection:

1
func loadUser(id int) (*User, error) {
2
    user, err := db.FindByID(id)
3
    if err != nil {
4
        return nil, fmt.Errorf("loadUser(%d): %w", id, err)
5
    }
6
    return user, nil
7
}

The caller can then unwrap it:

1
err := loadUser(42)
2
if errors.Is(err, ErrNotFound) {
3
    // still matches, even though the error was wrapped with extra context
4
}

8. Collections: Slices, Arrays, and Maps#

Arrays vs slices#

Arrays have a fixed size, determined at compile time:

1
var rgb [3]int                   // array: exactly 3 ints
2
colors := [3]string{"red", "green", "blue"}

Slices are dynamic-length views over arrays. Most code uses slices:

1
var names []string               // slice: length can change
2
scores := []int{95, 87, 92}     // slice literal

Creating slices with `make`#

make([]T, length) or make([]T, length, capacity):

1
// Length 5 — all elements start at zero value
2
numbers := make([]int, 5)           // [0, 0, 0, 0, 0]
3

4
// Length 0, capacity 10 — pre-allocates memory for efficiency
5
results := make([]string, 0, 10)    // [] but room for 10 items

make([]string, 0, 10) — creates an empty slice with pre-allocated capacity to avoid repeated allocations during append.

`append` — adding to slices#

1
fruits := []string{"apple", "banana"}
2
fruits = append(fruits, "cherry")
3
fruits = append(fruits, "date", "elderberry")    // add multiple at once
4

5
fmt.Println(fruits)
6
// [apple banana cherry date elderberry]

append may grow the underlying array if capacity is exceeded, returning a new slice header.
You must always reassign the result: fruits = append(fruits, ...) — without the reassignment, the new length (and possibly new backing array) is lost.

Expanding one slice into another:

1
moreFruits := []string{"fig", "grape"}
2
fruits = append(fruits, moreFruits...)    // ... expands the slice

Slice operations#

1
nums := []int{0, 1, 2, 3, 4, 5}
2

3
sub := nums[1:4]     // [1, 2, 3] — from index 1 up to (not including) 4
4
first3 := nums[:3]   // [0, 1, 2] — from start up to 3
5
last2 := nums[4:]    // [4, 5]    — from index 4 to end
6

7
length := len(nums)  // 6 — number of elements
8
cap := cap(nums)     // capacity of underlying array

Maps#

Maps are Go’s hash tables — like dictionaries or objects in other languages.

Declaration and initialization:

1
// Using make
2
ages := make(map[string]int)
3
ages["Alice"] = 30
4
ages["Bob"] = 25
5

6
// Using a literal
7
colors := map[string]string{
8
    "red":   "#ff0000",
9
    "green": "#00ff00",
10
    "blue":  "#0000ff",
11
}

map[string]int — keys are string, values are int.
Maps must be initialized with make or a literal before use. A nil map panics on write.

Checking if a key exists:

1
age, ok := ages["Charlie"]
2
if !ok {
3
    fmt.Println("Charlie not found")
4
} else {
5
    fmt.Println("Charlie is", age)
6
}

The two-value map lookup value, ok := m[key] returns ok == true if the key exists. This is the idiomatic way to check membership.

Deleting a key:

1
delete(ages, "Bob")    // removes the "Bob" entry

`range` — iterating over collections#

Over a slice:

1
fruits := []string{"apple", "banana", "cherry"}
2
for i, fruit := range fruits {
3
    fmt.Printf("%d: %s\n", i, fruit)
4
}
5

6
// If you only need the value:
7
for _, fruit := range fruits {
8
    fmt.Println(fruit)
9
}
10

11
// If you only need the index:
12
for i := range fruits {
13
    fmt.Println(i)
14
}

range returns (index, value) for slices. _ discards whichever you don’t need.

Over a map:

1
for name, age := range ages {
2
    fmt.Printf("%s is %d years old\n", name, age)
3
}

For maps, range returns (key, value). Iteration order is random.

9. Control Flow#

`for` — Go’s only loop#

Go has no while or do-while. The for keyword covers all loop patterns.

Classic 3-part loop:

1
for i := 0; i < 10; i++ {
2
    fmt.Println(i)
3
}

Condition-only loop (like while). Go has no while keyword — you use for with just a condition:

1
n := 1
2
for n < 100 {
3
    n *= 2
4
}
5
fmt.Println(n)    // 128

Infinite loop. for with no condition runs forever — you exit with return, break, or a channel signal:

1
for {
2
    input := readUserInput()
3
    if input == "quit" {
4
        break          // exit the loop
5
    }
6
    processInput(input)
7
}

For-range loop:

1
for i, item := range mySlice {
2
    fmt.Printf("Item %d: %v\n", i, item)
3
}

`if` with init statement#

Go’s if can include an initialization statement before the condition:

1
if err := doSomething(); err != nil {
2
    fmt.Println("Error:", err)
3
    return
4
}

err is scoped to this if block — it doesn’t leak into the surrounding function.
This is extremely common in Go for inline error handling.

Another example with map lookup:

1
if value, ok := myMap[key]; ok {
2
    fmt.Println("Found:", value)
3
} else {
4
    fmt.Println("Not found")
5
}

`switch`#

Switch on an expression:

1
switch day {
2
case "Monday":
3
    fmt.Println("Start of work week")
4
case "Friday":
5
    fmt.Println("Almost weekend!")
6
case "Saturday", "Sunday":
7
    fmt.Println("Weekend!")
8
default:
9
    fmt.Println("Midweek")
10
}

Note: unlike C/Java, Go switch cases do not fall through by default. Each case breaks automatically. If you want fallthrough, you must say it explicitly with the fallthrough keyword.

Switch with no expression — acts like a clean if/else chain:

1
switch {
2
case score >= 90:
3
    grade = "A"
4
case score >= 80:
5
    grade = "B"
6
case score >= 70:
7
    grade = "C"
8
default:
9
    grade = "F"
10
}

`defer`#

defer schedules a function call to run when the surrounding function returns. Deferred calls execute in LIFO order (last deferred = first executed).

Common use: close a resource

1
file, err := os.Open("data.txt")
2
if err != nil {
3
    return err
4
}
5
defer file.Close()    // guaranteed to run when the function returns
6

7
// ... use file ...
8
// file.Close() runs automatically, even if we return early due to an error

Common use: unlock a mutex

1
mu.Lock()
2
defer mu.Unlock()
3

4
// ... critical section ...
5
// Unlock runs when function returns, even if there's a panic

LIFO order with multiple defers:

1
func example() {
2
    defer fmt.Println("first deferred — runs LAST")
3
    defer fmt.Println("second deferred — runs SECOND")
4
    defer fmt.Println("third deferred — runs FIRST")
5
    fmt.Println("normal code")
6
}
7
// Output:
8
// normal code
9
// third deferred — runs FIRST
10
// second deferred — runs SECOND
11
// first deferred — runs LAST

defer is Go’s replacement for finally blocks. It guarantees cleanup even if the function panics.

`panic` and `recover`#

panic aborts the current function and unwinds the stack. It is used for programming errors and invariant violations — not for expected error conditions:

1
func mustPositive(n int) {
2
    if n <= 0 {
3
        panic(fmt.Sprintf("expected positive number, got %d", n))
4
    }
5
}

recover catches a panic inside a deferred function:

1
func safeCall(fn func()) (err error) {
2
    defer func() {
3
        if r := recover(); r != nil {
4
            err = fmt.Errorf("recovered from panic: %v", r)
5
        }
6
    }()
7
    fn()
8
    return nil
9
}

recover() only works inside a defer function — calling it elsewhere always returns nil.
The pattern is: defer func() { if r := recover(); r != nil { handle(r) } }(). The trailing () immediately invokes the anonymous function (but its execution is deferred).
Use panic/recover sparingly — idiomatic Go uses error return values for expected failures.

10. Concurrency#

Goroutines#

A goroutine is a lightweight thread managed by the Go runtime. You spawn one with the go keyword:

1
func sayHello(name string) {
2
    fmt.Printf("Hello, %s!\n", name)
3
}
4

5
func main() {
6
    go sayHello("Alice")     // runs concurrently
7
    go sayHello("Bob")       // runs concurrently
8

9
    time.Sleep(time.Second)  // wait for goroutines (crude — see WaitGroup below)
10
}

With an anonymous function:

1
go func(msg string) {
2
    fmt.Println(msg)
3
}("Hello from goroutine")    // arguments are passed immediately

The arguments ("Hello from goroutine") are evaluated immediately and passed to the goroutine. This avoids a common closure bug where loop variables change before the goroutine reads them.
Goroutines are extremely cheap — thousands can run simultaneously.

Channels#

Channels are typed pipes for communication between goroutines.

Unbuffered channels — make(chan T) with no size argument. The sender blocks until a receiver is ready:

1
ch := make(chan string)
2

3
go func() {
4
    ch <- "hello"    // send: blocks until someone receives
5
}()
6

7
msg := <-ch          // receive: blocks until someone sends
8
fmt.Println(msg)     // "hello"

ch <- value sends a value into the channel.
value := <-ch receives a value from the channel.
The arrow always points left — think of it as “data flows into the arrow.”

Buffered channels — make(chan T, capacity) with a size. The sender blocks only when the buffer is full:

1
ch := make(chan int, 3)    // buffer size 3
2

3
ch <- 1    // doesn't block — buffer has room
4
ch <- 2    // doesn't block
5
ch <- 3    // doesn't block
6
// ch <- 4  // WOULD block — buffer is full
7

8
fmt.Println(<-ch)    // 1
9
fmt.Println(<-ch)    // 2

Signal-only channels — chan struct{} carries no data. Used purely for notification:

1
done := make(chan struct{})
2

3
go func() {
4
    // ... do work ...
5
    close(done)           // signal that work is done
6
}()
7

8
<-done    // wait for the signal
9
fmt.Println("Work finished")

struct{} takes zero bytes, so the channel carries no data — it’s just a signal.
close(done) unblocks all receivers.

`select`#

select lets a goroutine wait on multiple channel operations simultaneously. It is like a switch but for channels:

1
func main() {
2
    ch1 := make(chan string)
3
    ch2 := make(chan string)
4

5
    go func() {
6
        time.Sleep(1 * time.Second)
7
        ch1 <- "one"
8
    }()
9
    go func() {
10
        time.Sleep(2 * time.Second)
11
        ch2 <- "two"
12
    }()
13

14
    select {
15
    case msg := <-ch1:
16
        fmt.Println("Received from ch1:", msg)
17
    case msg := <-ch2:
18
        fmt.Println("Received from ch2:", msg)
19
    }
20
}
21
// Prints "Received from ch1: one" (it arrives first)

Walking through this:

case msg := <-ch1: — if a value arrives on ch1, receive it and run this branch.
case msg := <-ch2: — if a value arrives on ch2, receive it and run this branch.
select blocks until one of the cases can proceed. If multiple are ready, one is chosen at random.

Timeout pattern:

1
select {
2
case result := <-ch:
3
    fmt.Println("Got result:", result)
4
case <-time.After(3 * time.Second):
5
    fmt.Println("Timed out!")
6
}

Non-blocking check — adding a default case makes select non-blocking:

1
select {
2
case msg := <-ch:
3
    fmt.Println("Received:", msg)
4
default:
5
    fmt.Println("No message available")
6
}

`sync.Mutex` — mutual exclusion#

A mutex protects shared data from concurrent access:

1
type SafeCounter struct {
2
    mu    sync.Mutex
3
    count int
4
}
5

6
func (c *SafeCounter) Increment() {
7
    c.mu.Lock()
8
    defer c.mu.Unlock()
9
    c.count++
10
}
11

12
func (c *SafeCounter) Value() int {
13
    c.mu.Lock()
14
    defer c.mu.Unlock()
15
    return c.count
16
}

sync.RWMutex allows multiple concurrent readers but only one writer:

1
type SafeMap struct {
2
    mu   sync.RWMutex
3
    data map[string]string
4
}
5

6
func (m *SafeMap) Get(key string) string {
7
    m.mu.RLock()              // multiple goroutines can RLock simultaneously
8
    defer m.mu.RUnlock()
9
    return m.data[key]
10
}
11

12
func (m *SafeMap) Set(key, value string) {
13
    m.mu.Lock()               // exclusive access for writing
14
    defer m.mu.Unlock()
15
    m.data[key] = value
16
}

`sync.WaitGroup` — waiting for goroutines#

A WaitGroup waits for a collection of goroutines to finish:

1
func main() {
2
    var wg sync.WaitGroup
3

4
    for i := 0; i < 5; i++ {
5
        wg.Add(1)              // increment counter before launching goroutine
6
        go func(id int) {
7
            defer wg.Done()    // decrement counter when goroutine finishes
8
            fmt.Printf("Worker %d done\n", id)
9
        }(i)
10
    }
11

12
    wg.Wait()                  // blocks until counter reaches 0
13
    fmt.Println("All workers finished")
14
}

wg.Add(1) — tell the WaitGroup one more goroutine is starting.
wg.Done() — tell the WaitGroup one goroutine is finished (decrements by 1).
wg.Wait() — block until all goroutines have called Done().

`sync.Once` — one-time initialization#

Ensures a function runs exactly once, even from multiple goroutines:

1
var (
2
    instance *Database
3
    once     sync.Once
4
)
5

6
func GetDatabase() *Database {
7
    once.Do(func() {
8
        instance = connectToDatabase()    // runs only on the first call
9
    })
10
    return instance
11
}

Common concurrency pattern: worker pool#

1
func main() {
2
    jobs := make(chan int, 100)
3
    results := make(chan int, 100)
4

5
    // Start 3 workers
6
    for w := 0; w < 3; w++ {
7
        go worker(jobs, results)
8
    }
9

10
    // Send 9 jobs
11
    for j := 0; j < 9; j++ {
12
        jobs <- j
13
    }
14
    close(jobs)
15

16
    // Collect results
17
    for r := 0; r < 9; r++ {
18
        fmt.Println(<-results)
19
    }
20
}
21

22
func worker(jobs <-chan int, results chan<- int) {
23
    for job := range jobs {
24
        results <- job * 2     // do some "work"
25
    }
26
}

jobs <-chan int — a receive-only channel (this function can only read from it).
results chan<- int — a send-only channel (this function can only write to it).
Channel direction in the type signature makes the intent clear and prevents misuse.

11. Testing#

Test file conventions#

Test files are named *_test.go and live in the same directory as the code they test. Go’s test runner finds them automatically.

1
math/calculator.go          // production code
2
math/calculator_test.go     // tests for calculator.go

Test functions#

Test functions must start with Test and take *testing.T:

1
package math
2

3
import "testing"
4

5
func TestAdd(t *testing.T) {
6
    result := Add(2, 3)
7
    if result != 5 {
8
        t.Errorf("Add(2, 3) = %d; want 5", result)
9
    }
10
}
11

12
func TestDivide(t *testing.T) {
13
    result, err := Divide(10, 2)
14
    if err != nil {
15
        t.Fatalf("unexpected error: %v", err)
16
    }
17
    if result != 5 {
18
        t.Errorf("Divide(10, 2) = %f; want 5", result)
19
    }
20
}

t.Errorf(...) reports a failure but continues running the test.
t.Fatalf(...) reports a failure and stops the test immediately.

Run tests with go test ./math/....

Table-driven tests#

The most common test pattern in Go — define a slice of test cases, iterate with range:

1
func TestAdd(t *testing.T) {
2
    tests := []struct {
3
        a, b     int
4
        expected int
5
    }{
6
        {1, 2, 3},
7
        {0, 0, 0},
8
        {-1, 1, 0},
9
        {100, -50, 50},
10
    }
11

12
    for _, tt := range tests {
13
        result := Add(tt.a, tt.b)
14
        if result != tt.expected {
15
            t.Errorf("Add(%d, %d) = %d; want %d", tt.a, tt.b, result, tt.expected)
16
        }
17
    }
18
}

[]struct{...}{...} — a slice of anonymous structs, defined and initialized inline.
Adding a new test case is just one more line in the slice.

Subtests allow individual test cases to have names:

1
func TestDivide(t *testing.T) {
2
    tests := []struct {
3
        name      string
4
        a, b      float64
5
        want      float64
6
        wantErr   bool
7
    }{
8
        {"normal", 10, 2, 5, false},
9
        {"divide by zero", 10, 0, 0, true},
10
    }
11

12
    for _, tt := range tests {
13
        t.Run(tt.name, func(t *testing.T) {
14
            got, err := Divide(tt.a, tt.b)
15
            if (err != nil) != tt.wantErr {
16
                t.Errorf("error = %v, wantErr %v", err, tt.wantErr)
17
                return
18
            }
19
            if got != tt.want {
20
                t.Errorf("Divide(%f, %f) = %f; want %f", tt.a, tt.b, got, tt.want)
21
            }
22
        })
23
    }
24
}

t.Run(name, func) creates a named subtest — the output shows which case failed.

Benchmark functions#

Benchmark functions start with Benchmark and take *testing.B:

1
func BenchmarkAdd(b *testing.B) {
2
    for i := 0; i < b.N; i++ {
3
        Add(100, 200)
4
    }
5
}

b.N is set by the test framework to get stable timing. Run benchmarks with go test -bench=. ./math/....

12. Common Patterns in Go#

`init()` functions#

init() runs automatically when a package is loaded — before main(). It takes no arguments and returns nothing:

1
package main
2

3
var config map[string]string
4

5
func init() {
6
    config = map[string]string{
7
        "host": "localhost",
8
        "port": "8080",
9
    }
10
}
11

12
func main() {
13
    fmt.Println(config["host"])    // "localhost" — init() already ran
14
}

A package can have multiple init() functions. They all run in the order they appear. This is used for registering drivers, setting defaults, and one-time setup.

Stringer interface#

If you define a String() string method on a type, fmt.Println and friends will use it automatically:

1
type Direction int
2

3
const (
4
    North Direction = iota
5
    East
6
    South
7
    West
8
)
9

10
func (d Direction) String() string {
11
    names := [...]string{"North", "East", "South", "West"}
12
    if d < North || d > West {
13
        return "Unknown"
14
    }
15
    return names[d]
16
}
17

18
func main() {
19
    fmt.Println(North)    // prints "North", not "0"
20
}

The comma-ok idiom#

Several Go operations use the two-value return to signal success:

1
// Map lookup
2
value, ok := myMap[key]
3

4
// Type assertion
5
str, ok := value.(string)
6

7
// Channel receive
8
msg, ok := <-ch           // ok is false when channel is closed and empty

Functional options pattern#

When a function needs many optional parameters, Go uses functional options:

1
type Server struct {
2
    host    string
3
    port    int
4
    timeout time.Duration
5
}
6

7
type Option func(*Server)
8

9
func WithPort(port int) Option {
10
    return func(s *Server) {
11
        s.port = port
12
    }
13
}
14

15
func WithTimeout(d time.Duration) Option {
16
    return func(s *Server) {
17
        s.timeout = d
18
    }
19
}
20

21
func NewServer(host string, opts ...Option) *Server {
22
    s := &Server{
23
        host:    host,
24
        port:    8080,               // default
25
        timeout: 30 * time.Second,   // default
26
    }
27
    for _, opt := range opts {
28
        opt(s)
29
    }
30
    return s
31
}
32

33
// Usage:
34
srv := NewServer("localhost", WithPort(9090), WithTimeout(5*time.Second))

The `sync.Pool` pattern#

For objects that are frequently allocated and discarded, sync.Pool recycles them to reduce garbage collection pressure:

1
var bufferPool = sync.Pool{
2
    New: func() interface{} {
3
        return new(bytes.Buffer)
4
    },
5
}
6

7
func process(data []byte) string {
8
    buf := bufferPool.Get().(*bytes.Buffer)    // get a recycled buffer (or new)
9
    defer bufferPool.Put(buf)                   // return it when done
10
    buf.Reset()                                 // clear previous content
11

12
    buf.Write(data)
13
    return buf.String()
14
}

Graceful shutdown pattern#

A common pattern for long-running services that need to shut down cleanly:

1
func main() {
2
    quit := make(chan os.Signal, 1)
3
    signal.Notify(quit, os.Interrupt, syscall.SIGTERM)
4

5
    srv := startServer()
6

7
    <-quit    // block until we receive a shutdown signal
8
    fmt.Println("Shutting down...")
9

10
    ctx, cancel := context.WithTimeout(context.Background(), 5*time.Second)
11
    defer cancel()
12
    srv.Shutdown(ctx)
13
}

Quick Reference #

Go	What it means
`:=`	Declare + assign (type inferred)
`_`	Blank identifier — discard a value
`&x`	Address of x (creates pointer)
`*p`	Value pointed to by p (dereference)
`*Type`	Pointer to Type
`[]Type`	Slice of Type
`[N]Type`	Array of N elements
`map[K]V`	Map from K to V
`chan T`	Channel carrying values of type T
`<-chan T`	Receive-only channel
`chan<- T`	Send-only channel
`interface{}` / `any`	Any type
`go f()`	Run f() in a new goroutine
`defer f()`	Run f() when this function returns
`x.(Type)`	Type assertion
`x.(type)`	Type switch (in switch only)
`Uppercase`	Exported (public)
`lowercase`	Unexported (package-private)
`...Type`	Variadic parameter
`slice...`	Expand slice into individual args
`make(T, ...)`	Allocate and initialize slice/map/channel
`new(T)`	Allocate zeroed T, return pointer

Welcome

What you’ll encounter when reading a .go file#