Go From Scratch (Beginner)¶

Beginner path: from never-coded to reading and contributing to real OSS Go.

Go From Scratch - Beginner to OSS Contributor¶

This path takes you from "I have never written code" to "I can clone a real Go project, read most of it, and submit a pull request for a small fix." It is unhurried, honest, and assumes nothing.

Who this is for¶

• You have never written code, OR
• You have copy-pasted code from tutorials but couldn't explain it line by line.

That's it. No "you should already know X." If you need to know something, this path will teach it.

What you'll need¶

• A computer (any OS - macOS, Linux, Windows all work).
• A text editor. VS Code is a good free default. Notepad/TextEdit work too, just less comfortable.
• A terminal. Built into every operating system.
• About 5 hours per week. The path is sized for ~4-6 months at that pace. Twice the hours, half the time. Half the hours, double the time. The path doesn't expire.

Why Go (and not some other language)¶

A few reasons that matter when you're starting:

1. The language is small. You can fit most of Go's syntax in your head. Other popular languages have more features than any person uses.
2. Errors are blunt. Go's compiler tells you exactly what's wrong and which line. You'll spend less time confused.
3. It's used in real things. Docker, Kubernetes, Terraform, much of cloud infrastructure is Go. The OSS projects you'll graduate to contributing to are real and important.
4. You'll be productive in weeks, not months. People who pick Go as their first language tend to ship something useful within a month.

How this path works¶

Each page does one thing:

1. Says what you'll learn this session.
2. Shows you a small program.
3. Walks through the code line by line.
4. Gives you a tiny exercise.

Do the exercises. Reading without doing won't stick - I promise. Type the code yourself; don't copy-paste. Your fingers learning Go is part of how your brain learns Go.

The deal¶

• I will not pretend things are easy when they aren't. When something is confusing the first time, I'll say so.
• I will not send you to "consult the primary source" or "read the standard library." If you need to know it, this path will teach it.
• There are no stupid questions, only stupid skipped exercises.
• The goal at the end is real: a pull request to a real open-source project. We will work up to it.

The pages¶

The path is 16 pages, sized so you can do one or two per week.

Start with Introduction.

00 - Introduction¶

What this session is¶

A 10-minute read. No code yet. The point is to set expectations honestly so you can decide if this path is for you.

What you're going to build, eventually¶

Programming is not a thing you watch - it's a thing you do. By the end of this path, you'll have done all of these:

• Written and run small programs that print, calculate, and make decisions.
• Built a little command-line tool that takes input and produces output.
• Written tests for your own code and watched them pass and fail.
• Cloned an open-source project off the internet, browsed its code, run its tests, and understood roughly what it does.
• Submitted a small fix to one of those open-source projects as a real pull request.

That last point is the goal. Everything else is preparation.

The deal we're making¶

A few things you should know about how this path works:

It's slow on purpose. Most beginner programming tutorials drop you into "build a real app" by page three. That works for some people. For most, it leaves them able to copy code without understanding it. This path is the opposite: one concept per page, with time to actually internalize each one.

It assumes nothing. If a word appears that you haven't seen, it'll be defined right there. No glossary lookups. No "see chapter 12."

It does the work where the work is. Some pages are short because the concept is small. Some are long because the concept is hard. We don't pad.

You have to type the code. Reading code without typing it has roughly the same effect as reading sheet music without playing it. Type every example, even when you "get it" from reading.

You will be confused. Often. Especially in the first month. That's normal. Programming is unusual in how often you feel stuck - the trick is not to panic when it happens. Re-read the page. Run the code. Change one thing and see what changes. Confusion is not a sign you're bad at this; it's a sign you're doing it.

What you need to start¶

• A computer. Any operating system works.
• A text editor. VS Code is free, multi-platform, and what I'd suggest unless you already love something else.
• A terminal. (On macOS it's the Terminal app. On Windows it's PowerShell or the Windows Terminal app. On Linux you already know.)
• ~5 hours per week. Less is fine; the path just takes longer.
• A specific notebook or text file where you can write down questions as they come up. You'll have lots. Writing them down lets you keep going past them; when you come back you can answer them with what you've since learned.

What you do NOT need¶

• Math beyond basic arithmetic. Programming uses arithmetic; it's not "advanced math."
• A computer-science degree, or any plan to get one.
• A "gift" for computers. There is no such thing. People who seem to "just get it" have spent more hours doing it than you have. That's all.
• To know any other programming language first. Go is a fine first language. Maybe a better first language than the usual recommendations.

How long this realistically takes¶

The honest answer: 4 to 6 months at 5 focused hours per week, to get to the "submit a pull request" goal.

If you have less time, take longer. If you have more time, take less. The path doesn't expire and the pages don't go stale.

I cannot make the time go faster. Nobody can. The thing that takes weeks is not "absorbing information" - it's your brain getting used to a new way of thinking. That happens at biology speed, not internet speed.

What success looks like at the end¶

You'll be able to:

• Open a Go file you've never seen and read it like a recipe - knowing what each piece does.
• Open a project on GitHub written in Go and tell me, in two paragraphs, what it does and how.
• Find a small bug or missing feature in such a project and fix it.
• Submit that fix as a pull request that follows the project's conventions.

You will not be able to:

• Build a new operating system. (Nobody can in 6 months.)
• Win competitive programming contests. (Different skill, mostly orthogonal.)
• Tell people you're a "senior engineer." (That takes years of doing the work after this path ends.)

What you will have: the foundation to keep going. Where you go from here is up to you.

One last thing before we start¶

If at any point a page feels too dense, stop and re-read it. If you re-read it and it's still too dense, that's a bug in the page - note it, skip forward, and come back. The path is alive; it gets fixed when readers say "this part lost me."

Ready? Next: Setup →

01 - Setup¶

What this session is¶

About 30 minutes. By the end you'll have Go installed, a place to put your code, and one tiny program that prints "hello, world" - the traditional first thing.

Step 1: Install Go¶

Go to go.dev/dl. Download the installer for your operating system.

• macOS: download the .pkg file. Double-click; follow the prompts.
• Windows: download the .msi file. Double-click; follow the prompts.
• Linux: either download the .tar.gz from go.dev/dl and follow the instructions there, or use your distro's package manager: sudo apt install golang-go on Debian/Ubuntu, sudo dnf install golang on Fedora.

Once it's done, open a terminal.

• macOS: press ⌘ Space, type "terminal", hit enter.
• Windows: press Windows, type "powershell", hit enter.
• Linux: you know how.

In the terminal, type:

go version

You should see something like:

go version go1.22.0 darwin/arm64

The version number and the bit after will be different - that's fine. As long as you see "go version" and a number, Go is installed.

If you get command not found or something similar, the install didn't work. On macOS, try opening a new terminal window (the path might not have updated in the old one). On Linux, the package manager version may be old; download from go.dev/dl directly instead.

Step 2: Pick a folder for your code¶

You're going to write a lot of small programs. They need somewhere to live.

Pick anywhere on your computer you can find again. I'll use ~/code/go-learning/ in my examples. (The ~ means your home folder. On macOS that's /Users/yourname; on Linux it's /home/yourname; on Windows it's C:\Users\yourname.)

In your terminal, create the folder and go into it:

mkdir -p ~/code/go-learning
cd ~/code/go-learning

Then check you're there:

pwd

pwd means "print working directory" - it shows where you are. You should see your new folder's path.

Step 3: The smallest possible Go program¶

Open your text editor (VS Code, or whatever you chose). Create a new file. Save it as hello.go inside the go-learning folder you just made.

Type this into the file - type it, don't copy-paste:

package main

import "fmt"

func main() {
    fmt.Println("hello, world")
}

Save the file.

Step 4: Run it¶

Back in your terminal, in the same folder as hello.go, type:

go run hello.go

You should see:

hello, world

That's your first program. Take a moment.

What just happened - line by line¶

You typed five lines (plus a blank one). Each one matters:

• package main - Every Go file says which "package" it belongs to. main is special: it's the package that becomes a runnable program. We'll come back to packages later; for now, just remember every program you write will start with this line.

• import "fmt" - Pulls in the fmt package (short for "format"). fmt has functions for printing and formatting text. To use code that lives somewhere else, you have to import it first.

• func main() - Defines a function called main. A "function" is a named block of code. main is special: it's the function that runs when the program starts. Every Go program needs exactly one main function in the main package.

• fmt.Println("hello, world") - Calls the Println function (the "Pl" stands for "print line") from the fmt package, with "hello, world" as the input. Println prints whatever you give it, then moves to a new line.

• The curly braces { and } mark the beginning and end of the function's body - the code that belongs to main.

Don't try to memorize this. You're going to type package main, import, func main() so many times in the next few sessions that it'll become automatic, like signing your name.

Try changing things¶

The way to learn is to break things on purpose and see what happens. Try each of these:

1. Change "hello, world" to your name. Run again. Did it work?

2. Add a second line that prints something else:

   fmt.Println("hello, world")
   fmt.Println("this is my second line")
   

3. Try printing a number - no quotes:

   fmt.Println(42)
   

4. Now break it on purpose. Remove the closing } and run. Read the error Go gives you. (Don't worry about understanding all of it - just notice that Go tells you which line is wrong.)

5. Put the } back. Now mistype Println as println (lowercase p). Run. Read the error. Go is case-sensitive: Println and println are different names.

Reading errors is most of programming. Get comfortable seeing them. They are not scary; they are the computer telling you what it noticed.

What you might wonder¶

"Why all this scaffolding for one print line?" Fair question. In Python you'd write print("hello, world") and that's the whole file. Go trades typing for predictability: every Go program has the same shape, so you always know where to look. You'll appreciate this when programs get bigger.

"Do I need to compile it?" go run does compiling AND running in one step - it builds your program in memory, runs it, throws the result away. Later you'll meet go build, which produces a separate executable file you can ship to other computers.

"What does the func mean?" Short for "function." It's how Go marks "here begins a function definition." You'll write it a lot.

"Are tabs or spaces required for the indentation?" Go uses tabs by convention. There's a tool called gofmt that reformats your code; we'll meet it soon. For now, your editor probably does the right thing if you press Tab.

Done¶

You have: - Go installed. - A folder to put your code in. - One working program.

This was the boring infrastructure step. Next page is where the real learning starts.

Next: First real program →

02 - First Real Program¶

What this session is¶

About 45 minutes. You'll learn three things: variables (storing data), types (kinds of data), and the expressions you can do with them. By the end you'll have written a program that uses all three.

Why variables exist¶

Programs do things with data. To do things with data, you have to store it somewhere named, so you can refer to it later.

That's all a "variable" is: a name attached to a piece of data.

A small program with variables¶

Open your go-learning folder. Create a new file called greet.go. Type this in:

package main

import "fmt"

func main() {
    name := "Alice"
    age := 30
    fmt.Println(name, "is", age, "years old")
}

Run it:

go run greet.go

You should see:

Alice is 30 years old

What's new here¶

Two lines you haven't seen before:

name := "Alice"
age := 30

Let's unpack name := "Alice":

• name is the name of a new variable.
• := is the "create and assign" operator. Read it as "is set to."
• "Alice" is the value we're putting into it. The double quotes mean it's text (a "string").

So name := "Alice" reads as: "create a variable called name and set it to the text Alice."

age := 30 does the same thing with a number. No quotes around 30 - numbers don't take quotes.

The last line:

fmt.Println(name, "is", age, "years old")

You've seen fmt.Println before. New thing: it can take multiple things separated by commas, and it prints them with spaces in between. We give it four things - the value of name, the text "is", the value of age, and the text "years old". Out comes one line with all four glued together by spaces.

Types: what kind of thing is this?¶

Every value in Go has a type. The type tells Go what kind of thing it is - text? a number? something else? - and what you can do with it.

You'll meet many types over time. The first three you need to know are:

Notice you didn't have to tell Go that name is a string and age is an int. Go figured it out from the values you gave them - "Alice" has quotes (must be a string), 30 doesn't (must be a number). This is called type inference.

There's a longer way to write the same thing, where you spell out the type:

var name string = "Alice"
var age int = 30

Both forms do the same thing. Use := when you can (it's shorter); save var for cases we'll meet later. But you'll see var in real code, so don't be surprised.

What you can do with numbers¶

The usual arithmetic works:

x := 10
y := 3
fmt.Println(x + y)   // 13
fmt.Println(x - y)   // 7
fmt.Println(x * y)   // 30
fmt.Println(x / y)   // 3
fmt.Println(x % y)   // 1

That // 13 part is a comment - anything after // on a line is ignored by Go. Comments are how you leave notes for yourself (or future readers) in the code.

Three things to notice:

• x / y gave 3, not 3.333.... That's because x and y are ints - integers, whole numbers. Integer division throws away the remainder. To get the decimal answer you need a different type (float64), which we'll meet when we actually need it.
• x % y gave 1. The % operator gives the remainder after division. 10 / 3 is 3 with 1 left over, so 10 % 3 is 1. We'll use this often to test "is this number even?" (n % 2 == 0 is true if n is even).
• Both operands have to be the same type. You can't x + "hello".

What you can do with strings¶

You can stick two strings together with +:

greeting := "hello"
name := "world"
message := greeting + ", " + name
fmt.Println(message)   // hello, world

The technical word for "stick two strings together" is concatenate. You'll hear it.

Notice the same symbol + does two different jobs: - Between numbers: addition. - Between strings: concatenation.

This is normal in programming languages. Go uses the type to decide which job to do.

What you cannot do is mix:

n := 5
s := "items: "
fmt.Println(s + n)   // ERROR

Try it. Go will refuse to compile. The error will say something like "invalid operation: s + n (mismatched types string and int)". The fix: turn the number into a string first.

The most-used tool for this is fmt.Sprintf. It's like Println but instead of printing, it builds a string and gives it back to you:

n := 5
s := fmt.Sprintf("items: %d", n)
fmt.Println(s)   // items: 5

The %d is a placeholder that means "put a number here." fmt.Sprintf looks at the first argument (the template) and fills in %d with the value of n.

You'll meet other placeholders: - %d - for numbers. - %s - for strings. - %v - for "any value, use the default representation."

You don't need to memorize them all. When you can't remember, write %v and it'll usually do the right thing.

What you can do with booleans¶

A bool is just true or false. You'll use them in decisions (next page). For now:

isReady := true
hasPermission := false
fmt.Println(isReady, hasPermission)   // true false

Exercise¶

Type this in a new file called me.go:

Write a program that:

1. Has a variable for your name (a string).
2. Has a variable for your favorite number (an int).
3. Has a variable for whether it's morning right now (a bool).
4. Prints a line like: "Hi, I'm Victor, my favorite number is 7, and yes (true) it's morning."

Try it two ways: - First with multiple arguments to fmt.Println (fmt.Println("Hi, I'm", name, ...)). - Then with fmt.Sprintf and %s, %d, %v placeholders, building one big string and printing it once.

Don't skip this. The act of typing is the learning.

What you might wonder¶

"Why does integer division throw away the remainder?" Because integers can't represent fractional values. 10 / 3 has to give some integer answer - Go picks the closest one that fits, which is 3. If you want 3.333..., you need decimals, which is a different type (float64). We'll meet floats when we need them.

"Why does Go yell at me for mixing strings and numbers?" By design. In some languages, adding a number to a string silently converts the number ("items: " + 5 becomes "items: 5"). That seems nice until you have a bug where you accidentally concatenated when you meant to add. Go refuses on purpose; you have to be explicit about what you want.

"What happens if I never use a variable I declared?" Go won't compile. This is on purpose too - unused variables are usually bugs (you typed the wrong name somewhere). Either use the variable, or delete the line.

Done¶

You can now: - Make variables and give them values. - Tell apart the three basic types: int, string, bool. - Do arithmetic on numbers. - Stick strings together. - Build a string with fmt.Sprintf and placeholders.

Next page: making your program decide and repeat.

Next: Decisions and loops →

03 - Decisions and Loops¶

What this session is¶

About an hour. You'll learn how to make your program decide between options (with if) and how to make it repeat something (with for). These two things are the building blocks of every program that does anything more than print a fixed message.

Decisions with if¶

The world's smallest decision:

package main

import "fmt"

func main() {
    age := 18
    if age >= 18 {
        fmt.Println("adult")
    } else {
        fmt.Println("minor")
    }
}

Run it. You'll see adult.

Now change age := 18 to age := 15 and run it again. You'll see minor.

What's happening:

• if age >= 18 { ... } - run the code in the braces only if age >= 18 is true.
• else { ... } - if the condition was false, run this code instead.

The condition is whatever's between if and {. It must evaluate to a bool - true or false.

Comparison operators¶

The operators that produce true/false:

A common mistake: writing = (one equals sign) when you mean == (two). = is assignment ("set this to that"); == is comparison ("does this equal that?"). Go will give a compile error if you mix them up; just notice it now.

Chaining decisions with else if¶

What if you have more than two cases?

score := 75
if score >= 90 {
    fmt.Println("A")
} else if score >= 80 {
    fmt.Println("B")
} else if score >= 70 {
    fmt.Println("C")
} else {
    fmt.Println("F")
}

Reads top to bottom. The first condition that's true wins; everything else is skipped. If none match, the else block runs.

Combining conditions: &&, ||, !¶

You can build bigger conditions out of smaller ones:

Example:

age := 25
hasLicense := true
if age >= 18 && hasLicense {
    fmt.Println("can drive")
}

The condition is true only when both halves are true.

Repetition: for¶

This is the part that takes a few tries to internalize. Read carefully.

Print the numbers 1 through 5:

for i := 1; i <= 5; i++ {
    fmt.Println(i)
}

That for line is doing three things, separated by semicolons:

1. i := 1 - create a variable i starting at 1. (This happens once, before anything else.)
2. i <= 5 - the condition that keeps the loop going. Checked before each round.
3. i++ - what to do after each round. (i++ is shorthand for i = i + 1.)

The flow is:

1. Set i = 1. Check 1 <= 5. True → run the body. Print 1. Then do i++ → i = 2.
2. Check 2 <= 5. True → print 2. Then i = 3.
3. ... continues ...
4. Check 5 <= 5. True → print 5. Then i = 6.
5. Check 6 <= 5. False → stop.

Output:

1
2
3
4
5

Type this in. Run it. Change 1 to 10 and <= 5 to <= 20. Change i++ to i = i + 2 and see what happens. The way to internalize loops is to mess with them.

Two shorter forms¶

The "keep going while X" form, when you don't have a counter:

n := 10
for n > 0 {
    fmt.Println(n)
    n = n - 1
}

This prints 10, 9, 8, ..., 1. There's no "init" or "after each round" part - just the condition. The body has to do whatever changes the condition, otherwise the loop never stops.

The "forever" form, when you'll stop from inside:

for {
    // runs until you break out
}

Useful in programs that wait for events, listen on a socket, etc. We'll see real uses later.

Breaking out early: break and continue¶

break stops the loop entirely.

continue skips to the next round, without running the rest of the body this time.

for i := 1; i <= 10; i++ {
    if i == 5 {
        break // stop the whole loop when i is 5
    }
    if i%2 == 0 {
        continue // skip the print for even numbers
    }
    fmt.Println(i)
}

Output: 1, 3. Why?

• i=1: not 5, not even → print 1.
• i=2: not 5, even → continue (skip print).
• i=3: not 5, not even → print 3.
• i=4: even → skip.
• i=5: break → stop entirely.

Putting it together¶

A small program that classifies the numbers 1 to 10:

package main

import "fmt"

func main() {
    for i := 1; i <= 10; i++ {
        if i%2 == 0 {
            fmt.Println(i, "even")
        } else {
            fmt.Println(i, "odd")
        }
    }
}

Type and run. Read the output. Read the code. Look at each line and ask: which line produced this output?

Exercise¶

Type this in a new file called classify.go:

Write a program that, for each number from 1 to 20:

• If the number is divisible by 3, print Fizz instead of the number.
• If the number is divisible by 5, print Buzz instead.
• If divisible by both 3 and 5, print FizzBuzz.
• Otherwise print the number.

(This is the classic "FizzBuzz" problem. It's famous as a small interview question, and a very good exercise for cementing if/else if/else with a loop.)

Hint: check the "both 3 and 5" case first. Why? Think about what would happen if you checked "divisible by 3" first.

When you finish, the output should be:

1
2
Fizz
4
Buzz
Fizz
7
8
Fizz
Buzz
11
Fizz
13
14
FizzBuzz
16
17
Fizz
19
Buzz

Don't move on until your program prints exactly this.

What you might wonder¶

"What about while loops?" Other languages have a separate while keyword. Go doesn't - for condition { } does the same thing. One loop keyword, fewer things to remember.

"What about do-while?" Use:

for {
    // body that should run at least once
    if !condition {
        break
    }
}

"Why doesn't Go have i++ as an expression?" In some languages j = i++ is legal and confusing. In Go, i++ is a statement on its own line - it doesn't return a value. This rules out a category of bugs that show up in C and C++.

"Why braces on if even for one line?" In some languages you can write if (cond) doThing(); without braces. Go requires the braces always. This is opinionated but on purpose - a category of bugs (forgetting braces, then adding a second line that doesn't actually belong to the if) becomes impossible.

Done¶

You can now: - Make a program take different actions based on conditions (if, else if, else). - Combine conditions with &&, ||, !. - Repeat actions with for, in three forms. - Exit a loop early with break, skip an iteration with continue.

You now have the basic shapes that every program is built from. Combined with what you learned in Page 02, you can in principle write any program - just very, very long ones.

The next page is the abstraction that lets your programs stay short as they get bigger: functions.

Next: Functions →

04 - Functions¶

What this session is¶

About an hour. You'll learn how to define your own functions, and why doing so changes everything about how you write programs.

The problem functions solve¶

So far every program you've written has been one block of code inside main(). That works for 5-line programs. It stops working around 30 lines, for three reasons:

1. You can't see what the program does by looking at it. The structure is gone.
2. You can't reuse anything. If you compute "the square of a number" in three places, you've typed x * x three times.
3. You can't test pieces. The whole program runs or doesn't run; you can't easily check one calculation in isolation.

A function solves all three. It's a named block of code that takes some input and (usually) gives you some output back.

The shape of a function¶

func name(parameters) returnType {
    // body
    return something
}

Concrete example:

package main

import "fmt"

func double(x int) int {
    return x * 2
}

func main() {
    fmt.Println(double(5))   // 10
    fmt.Println(double(7))   // 14
}

Type it. Run it. You should see 10 and 14.

Walk through it slowly:

• func double(x int) int { - defines a function called double. It takes one input (called a parameter), named x, of type int. It returns an int. The body is between the curly braces.
• return x * 2 - computes x * 2 and sends that value back to whoever called the function.
• double(5) - calls the function with 5 as the value of x. The function runs, returns 10, and Println prints it.

Notice the function double exists outside main. Functions go at the top level of the file, not nested inside main. (Other languages let you nest them; Go does not, in the basic form.)

Multiple parameters¶

A function can take more than one input:

func add(a int, b int) int {
    return a + b
}

Or, when several parameters share a type, you can collapse the declaration:

func add(a, b int) int {
    return a + b
}

Both forms mean the same thing. The second is more idiomatic in Go.

Functions that don't return anything¶

Sometimes a function just does something - it doesn't produce a value to give back. In that case, leave out the return type:

func sayHi(name string) {
    fmt.Println("Hi,", name)
}

func main() {
    sayHi("Alice")
    sayHi("Bob")
}

sayHi doesn't return anything. There's no return line in its body. Its job is just to print.

The unusual thing: returning two values at once¶

In most languages, a function returns one thing. Go lets you return two or more things at once. This is uncommon enough to be worth its own section.

func divide(a, b int) (int, int) {
    quotient := a / b
    remainder := a % b
    return quotient, remainder
}

func main() {
    q, r := divide(17, 5)
    fmt.Println("quotient:", q, "remainder:", r)
    // quotient: 3 remainder: 2
}

Type and run.

The new things:

• func divide(a, b int) (int, int) { - the return type is (int, int). The parentheses mean "two things, both ints."
• return quotient, remainder - return both, separated by a comma.
• q, r := divide(17, 5) - receive both, by writing two names separated by a comma on the left of :=.

This pattern is everywhere in Go. The reason: Go's whole story for handling errors (which you'll learn in a later page) uses it. Every function that can fail returns two things: the result it computed, and an error value telling you whether something went wrong. We'll get there.

For now, just internalize: in Go, "two return values" is normal.

Why functions are worth the trouble¶

Here's a small program that uses two functions:

package main

import "fmt"

func square(x int) int {
    return x * x
}

func sumOfSquares(a, b int) int {
    return square(a) + square(b)
}

func main() {
    fmt.Println(sumOfSquares(3, 4))   // 9 + 16 = 25
}

Look at sumOfSquares. It calls square twice. Functions can call other functions. This is how programs get built up - small named pieces, composed.

Now imagine you write the same logic without functions:

func main() {
    a := 3
    b := 4
    result := (a * a) + (b * b)
    fmt.Println(result)
}

Shorter, sure. But: - The reader has to figure out what (a * a) + (b * b) means. sumOfSquares(3, 4) says it. - If you need the squares in three different places, you re-type x * x three times. - If you later decide squaring should clamp to a maximum (say, return 1000 if the result is bigger), you change one function. In the long version, you change every place.

These benefits compound. They're invisible at 30 lines and decisive at 300.

Variables inside vs outside¶

A variable declared inside a function exists only inside that function. The technical word is scope.

func double(x int) int {
    result := x * 2
    return result
}

func main() {
    fmt.Println(result)   // ERROR - `result` doesn't exist out here
}

Each function has its own world. Variables don't leak between them. The way to get information into a function is parameters; the way to get information out is the return value(s).

Exercise¶

In a new file iseven.go:

1. Write a function isEven(n int) bool that returns true if n is even and false otherwise.

Hint: use the % operator from Page 02. n % 2 == 0 is a bool.

1. From main, print isEven(4) and isEven(7). You should see true and false.

2. Write a second function countEvens(max int) int that counts how many even numbers are in 1, 2, 3, ..., max. It should use a for loop and call your isEven function for each.

3. From main, print countEvens(10). You should see 5 (the evens 2, 4, 6, 8, 10).

4. Now print countEvens(0). What happens? Is that what you expected?

Don't move on until your code works for both countEvens(10) and countEvens(100) (expected: 50).

What you might wonder¶

"Why do I have to declare the return type?" So Go can catch mistakes for you at compile time. If you say double returns an int and you accidentally write return "hello", Go refuses to build the program and tells you exactly what's wrong. The alternative - types figured out at runtime, like in Python - means some bugs only show up when a real user hits them. Go trades a small amount of typing for a large reduction in runtime surprises.

"What if my function has nothing to return but I forgot to handle a case?" If you declare a return type but a path through your function doesn't return anything, Go refuses to compile. You'll see "missing return at end of function." This is on purpose - it catches the "I forgot the else branch" bug.

"Can a function call itself?" Yes. That's called recursion and it's a useful tool for certain problems. We'll meet it later when we have something worth recursing through.

"Can I have two functions with the same name?" No, not in the same package. Pick distinct names.

Done¶

You can now: - Define your own functions with parameters and a return type. - Return zero, one, or two values from a function. - Call functions from other functions. - Use functions to give names to operations and compose programs out of small pieces.

You've now learned the core of imperative programming in Go: variables, types, expressions, decisions, loops, and functions. Every Go program - including the ones in real OSS projects you'll eventually contribute to - is built from these primitives. The remaining pages introduce things that make those primitives more powerful: ways to group data (structs), ways to handle many things (slices and maps), ways to handle failure (errors), and so on.

The next page introduces structs - how Go lets you make your own types that group related data together. This is where your programs start to model real-world things.

Next: Making your own types → 05-structs-and-methods.md

05 - Structs, Methods, and Interfaces¶

What this session is¶

A long one - about ninety minutes. You'll learn the three constructs that make Go feel like Go: structs (group related data), methods (functions attached to a type), and interfaces (a contract that says "if your type has these methods, you can use it anywhere this kind of thing is expected"). These three together are what people mean when they say Go is "lightweight object-oriented" - there are no classes, no inheritance, but you can still model real things and write code that's flexible and testable.

This chapter is denser than the others. If it feels like a lot, take the main flow first; the Going deeper section at the end is for after you've used the material once or twice.

The problem this solves¶

So far, every piece of data you've worked with has been a single value - one int, one string, one bool. Real things have many properties at once. A person has a name, an age, a city. A point on a graph has an x and a y. A rectangle has a width and a height.

You could pass each property as a separate parameter:

func describe(name string, age int, city string) {
    fmt.Printf("%s, age %d, lives in %s\n", name, age, city)
}

That works for two or three. At six, you're sad. At twelve, you're lost. A struct lets you bundle them up.

A struct¶

package main

import "fmt"

type Person struct {
    Name string
    Age  int
    City string
}

func main() {
    alice := Person{Name: "Alice", Age: 30, City: "Lagos"}
    fmt.Println(alice)
    fmt.Println(alice.Name)
    fmt.Println(alice.Age)
}

Type it. Run it. You'll see:

{Alice 30 Lagos}
Alice
30

What's new:

• type Person struct { ... } - defines a new type called Person. It's a struct (a bundle of fields). The fields are listed inside the braces, one per line, each with a name and a type.
• Person{Name: "Alice", Age: 30, City: "Lagos"} - creates a value of type Person, with the listed fields set. This is called a struct literal.
• alice.Name - dot notation to read a field. Works the same way to write: alice.Name = "Alicia" changes the name.

Naming convention: types are CapitalCase. Field names are also CapitalCase if you want them visible outside the package (more on that in page 11). For now, capitalize everything.

Structs as function parameters and returns¶

A struct value is just like any other value - you can pass it to functions and return it from them:

package main

import "fmt"

type Point struct {
    X, Y int
}

func origin() Point {
    return Point{X: 0, Y: 0}
}

func describe(p Point) {
    fmt.Printf("at (%d, %d)\n", p.X, p.Y)
}

func main() {
    o := origin()
    describe(o)
    describe(Point{X: 3, Y: 4})
}

Notice X, Y int - when adjacent fields share a type, you can group them on one line. Same idea as parameters.

Methods: functions attached to a type¶

A method is a function that belongs to a type. The only difference from a regular function is the receiver - an extra parameter declared before the function name.

package main

import (
    "fmt"
    "math"
)

type Point struct {
    X, Y float64
}

func (p Point) DistanceFromOrigin() float64 {
    return math.Sqrt(p.X*p.X + p.Y*p.Y)
}

func main() {
    p := Point{X: 3, Y: 4}
    fmt.Println(p.DistanceFromOrigin())   // 5
}

The line:

func (p Point) DistanceFromOrigin() float64 {

reads as: "define a method called DistanceFromOrigin. It's attached to the Point type. Inside the method, the value the method was called on is named p."

So p.DistanceFromOrigin() calls the method with p as the receiver.

New thing in this example: float64 is a type for numbers with decimal places. math.Sqrt takes a float64. We changed Point.X and Point.Y from int to float64 so it works.

You could have written this as a regular function:

func distanceFromOrigin(p Point) float64 { ... }

That's not wrong. But methods read better at the call site:

p.DistanceFromOrigin()        // method
distanceFromOrigin(p)         // regular function

The method form puts the most important thing (the point) first. As programs get bigger, this matters.

Value vs pointer receivers (the mental model)¶

There's a second form of receiver, with a * in front of the type:

func (p *Point) MoveBy(dx, dy float64) {
    p.X += dx
    p.Y += dy
}

This is a pointer receiver. The previous one (func (p Point) ...) is a value receiver.

The simple rule: a value receiver gets a copy; a pointer receiver gets the original.

Why this matters - concrete demo:

type Counter struct{ Value int }

func (c Counter)  IncByValue()   { c.Value++ }     // operates on a copy
func (c *Counter) IncByPointer() { c.Value++ }     // operates on the original

func main() {
    c := Counter{}
    c.IncByValue()
    c.IncByValue()
    fmt.Println(c.Value)     // 0 - both increments mutated a copy and threw it away

    c.IncByPointer()
    c.IncByPointer()
    fmt.Println(c.Value)     // 2 - both increments wrote through to c
}

You'll meet pointers in full on page 08. For now, the practical rules of thumb:

• If the method changes a field of the receiver → use *Type. Otherwise the change won't stick.
• If the receiver is a big struct (lots of fields, or fields that are themselves big) → use *Type even if you don't modify it. A pointer is one machine word; copying the whole struct would be wasted work.
• If the receiver is small and immutable → either works. Pick one and use it for all methods on that type - consistency matters more than the choice itself.

When in doubt: use *Type. Real Go code uses pointer receivers around 80% of the time.

A bit of magic that makes this nicer: when you call c.IncByPointer() and c is a regular value (not a pointer), Go silently rewrites the call to (&c).IncByPointer() for you. The & is inserted automatically if c is addressable - that is, if it has a name (a variable, a struct field of a variable, an array element of a variable). This is why both c.IncByValue() and c.IncByPointer() look the same at the call site, even though the second technically requires a pointer. There's a corner case where this doesn't work - when the value is non-addressable, like a struct returned by a function - but you'll meet that rarely.

Try it: 1. Type the Counter example. Confirm the output is 0 then 2.

1. Try Counter{Value: 5}.IncByPointer() directly. Compile error: "cannot take the address of Counter{Value: 5}" - the struct literal has no name, so it's non-addressable. You can't take its address, so the auto-& insertion can't happen. Assign it to a variable first.

2. Change IncByValue to also return c (so it returns the copy after incrementing). Call c = c.IncByValue(). Now the change sticks - because you're explicitly assigning the returned copy back. This is how append works, by the way.

Methods on non-struct types¶

Methods aren't only for structs. You can define a method on any named type declared in the same package - including a named alias of int, string, float64, even a function type.

package main

import "fmt"

type ByteSize float64

const (
    _           = iota
    KB ByteSize = 1 << (10 * iota)
    MB
    GB
)

func (b ByteSize) String() string {
    switch {
    case b >= GB:
        return fmt.Sprintf("%.2f GB", b/GB)
    case b >= MB:
        return fmt.Sprintf("%.2f MB", b/MB)
    case b >= KB:
        return fmt.Sprintf("%.2f KB", b/KB)
    }
    return fmt.Sprintf("%d B", int(b))
}

func main() {
    var size ByteSize = 5_000_000
    fmt.Println(size)              // "4.77 MB"
}

That's a lot of new things in one example. Let's walk through it line by line so none of it is magic.

type ByteSize float64 - defines a brand-new type that has the same underlying representation as float64 but is a distinct type from the compiler's point of view. You can't add a ByteSize to a float64 without an explicit conversion - the compiler treats them as separate, even though they're the same shape in memory. This is exactly what lets us attach a method to it: methods can only be defined on named types declared in the current package, and float64 doesn't qualify (it's a built-in).

What is iota? Inside a const ( ... ) block, iota is a special built-in identifier that starts at 0 on the first line and increments by 1 on every subsequent line. That's the whole rule. So:

const (
    a = iota   // a = 0
    b = iota   // b = 1
    c = iota   // c = 2
)

It's just a line-numbered counter, scoped to one const block. The first time iota shows up in a fresh const block, it's 0; the next line, 1; and so on. Go doesn't have an enum keyword - iota is how you build one.

Why is the first line _ = iota? The _ (blank identifier) means "throw this value away." We're consuming the line iota = 0 deliberately, because we don't want KB to be on the first line - if KB were on the first line, its calculation would use iota = 0, and we'll see in a second why that would give us the wrong number.

What does 1 << (10 * iota) actually compute? << is the bit-shift left operator. 1 << n means "take the number 1 and shift its bit n places to the left," which (for non-negative n) is exactly the same as 2^n. So:

• 1 << 10 is 2^10 which is 1024.
• 1 << 20 is 2^20 which is 1,048,576 (about 1 million).
• 1 << 30 is 2^30 which is 1,073,741,824 (about 1 billion).

Those three numbers are exactly 1 KB, 1 MB, and 1 GB in binary units (the "real" units a computer uses, as opposed to the decimal 1,000 / 1,000,000 / 1,000,000,000 that hard-drive marketing uses). Now apply the iota counter:

• Line _ = iota -> iota = 0. Value discarded. (If we had written KB = 1 << (10 * 0) here we'd get KB = 1, not KB = 1024 - that's the line we wanted to skip.)
• Line KB ByteSize = 1 << (10 * iota) -> iota = 1, so KB = 1 << 10 = 1024.
• Line MB -> iota = 2, so MB = 1 << 20 = 1,048,576.
• Line GB -> iota = 3, so GB = 1 << 30 = 1,073,741,824.

Wait - MB and GB don't have an = sign. How does Go know what they equal? A second Go rule for const blocks: if a line omits its right-hand side, Go silently repeats the previous line's expression (verbatim - including the iota reference, which has advanced). So MB re-uses 1 << (10 * iota) with iota now equal to 2, and GB re-uses it again with iota = 3. This "repeat the previous expression" rule is why iota-based enums in Go are so compact: you write the formula once on the first real line, and every subsequent line silently re-applies it with a fresh iota.

Three rules, working together: (1) iota counts lines in a const block; (2) 1 << n is 2^n; (3) an omitted RHS repeats the previous expression. That's the entire trick - no magic.

The String() string method. A method named exactly String with signature () string is special: it makes the type satisfy a built-in interface called fmt.Stringer. We haven't talked about interfaces yet (next section!), but here's the punchline now: whenever you pass a value to fmt.Println, fmt.Printf("%v", ...), or any of the fmt family, the package checks at runtime "does this value have a String() method?" If yes, it calls that method to get the printable form. If no, it falls back to the default formatting.

That's why fmt.Println(size) prints "4.77 MB" and not the raw float 4.76837158203125e+06: size is a ByteSize, ByteSize has a String() method, so Println calls it and prints whatever it returns.

And the "4.77 MB" itself? size is 5,000,000. The switch in String() checks: is 5,000,000 >= GB (about a billion)? No. Is it >= MB (about a million)? Yes. So we return fmt.Sprintf("%.2f MB", b/MB) -> 5,000,000 / 1,048,576 = 4.768... -> formatted as "4.77 MB". The division is real number division because ByteSize is float64 underneath, which is why we get .77 and not just an integer.

You can even define methods on a function type - Go's standard library uses this pattern in http.HandlerFunc:

type HandlerFunc func(http.ResponseWriter, *http.Request)

func (f HandlerFunc) ServeHTTP(w http.ResponseWriter, r *http.Request) {
    f(w, r)
}

A HandlerFunc is a function, but it also has a method (ServeHTTP). Why? So a plain function can be passed wherever an http.Handler interface is expected. We'll see the trick in detail in Going deeper.

The only restriction: the receiver's base type must be defined in the same package as the method. You can't add methods to int (a built-in) or to types from other packages (time.Time, bytes.Buffer, etc.). Define your own named type if you want to extend something.

Try it:

1. Run the ByteSize example. Try printing ByteSize(500), ByteSize(2_000_000_000). The output adapts to scale.

2. Try var size ByteSize = 1.5; var f float64 = size. Compile error: cannot use size (type ByteSize) as type float64. You need an explicit conversion: f := float64(size). The distinct-type rule has teeth.

3. Define type WordCount int with a method Plural() string that returns "words" if the count != 1 and "word" otherwise. Use it: fmt.Println(WordCount(3).Plural()).

Interfaces: the contract¶

Here's the question interfaces solve: how do you write a function that works with anything that can do a certain thing, without knowing what that thing is?

Example. You want a function that writes some text "somewhere." Maybe a file. Maybe the terminal. Maybe a network connection. Maybe a memory buffer (for testing). They're all completely different concrete types, but they all support the operation "write some bytes." You want one function that takes any of them.

That's an interface. An interface is a contract that says "anything that has these methods can be used here."

package main

import "fmt"

// Any type with a Bark() method satisfies this interface.
type Barker interface {
    Bark() string
}

type Dog struct{ Name string }
func (d Dog) Bark() string { return d.Name + " says woof!" }

type Fox struct{ Name string }
func (f Fox) Bark() string { return f.Name + " says ???" }

// makeNoise accepts ANY type that satisfies Barker.
func makeNoise(b Barker) {
    fmt.Println(b.Bark())
}

func main() {
    makeNoise(Dog{Name: "Rex"})       // Rex says woof!
    makeNoise(Fox{Name: "Renard"})    // Renard says ???
}

Barker is a contract: "you can use anything as long as it has a Bark() string method." Dog has one. Fox has one. Both can be passed to makeNoise. makeNoise doesn't know or care about the concrete type - it just calls .Bark().

That's it. That's the whole idea. An interface is a behavior specification, and any type with the right methods automatically satisfies it.

Two pieces of syntax:

• type Barker interface { Bark() string } - declares the interface type, listing the methods it requires.
• func makeNoise(b Barker) - uses Barker like any other type. Inside the function, b is an interface value; only the methods listed in the interface are available on it.

The one-method -er naming convention is universal in Go: io.Reader, io.Writer, fmt.Stringer, sort.Interface, error. When an interface has one method, name the interface after the method plus -er.

Try it: 1. Type the example. Confirm it prints both lines.

1. Add a type Cat struct{ Name string } without a Bark() method. Try makeNoise(Cat{Name: "Whiskers"}). Compile error: "Cat does not implement Barker (missing Bark method)". The compiler checks at compile time, before your program runs.

2. Add a func (c Cat) Bark() string { return c.Name + " meows" }. Now makeNoise(Cat{...}) works. The cat satisfies Barker purely because it has the right method - even though we never wrote anywhere that Cat "is a" Barker.

Implicit satisfaction: the Go way¶

The previous example showed something quietly profound: Cat satisfied Barker automatically. We never wrote class Cat implements Barker (Java), nor class Cat : public Barker (C++). The Cat type and the Barker interface might even be in different packages, written by different people, who never heard of each other.

This is called implicit interface satisfaction, and it's the central Go design choice for code reuse. The rule:

A type satisfies an interface as soon as it has all the methods the interface requires. No declaration is needed.

Three big consequences:

1. You can define an interface for a type you didn't write. Maybe you import a package with a type pdf.Document that has a Title() string method. You can define your own type Titled interface { Title() string } and use it to accept pdf.Document (and anything else with a Title() string). You don't need access to the original code.

2. You can add a new method to your own type and it automatically starts satisfying every interface that wants that method. The connections are made by the compiler at the points where you assign a concrete type to an interface variable.

3. Small interfaces become normal. Because you don't have to design hierarchies up front, real Go code is dotted with tiny one- or two-method interfaces, each precise about what it requires. io.Reader has one method. error has one method. fmt.Stringer has one method. The standard library's most flexible types satisfy dozens of different one-method interfaces.

Contrast with how you'd write this in Java:

// Java: every type that wants to be Barker must explicitly declare it.
public interface Barker {
    String bark();
}

public class Dog implements Barker {     // explicit "implements"
    public String bark() { return "woof"; }
}

In Java, Dog must know about Barker at the moment it's defined. In Go, the relationship goes the other way: Barker (or any future interface) can discover Dog later, just by needing a method Dog happens to have. The decoupling is the win.

Try it: 1. Look at the standard library's fmt.Stringer:

type Stringer interface { String() string }

1. That's how fmt.Println(size) printed "4.77 MB" earlier. The fmt package internally does if s, ok := v.(Stringer); ok { return s.String() }. Your ByteSize.String() got called because ByteSize happens to satisfy Stringer.

2. The error type you've been using is also an interface: type error interface { Error() string }. Same mechanism. Any type with Error() string is an error.

A practical example: fmt.Stringer¶

fmt.Stringer is the most common interface a beginner runs into. It's used by the fmt package to ask types "how do you want to be printed?" Implement it once, and fmt.Println, fmt.Printf with %v, fmt.Sprintf, and string interpolation all use your version.

package main

import "fmt"

type Money struct {
    Amount   int64   // in cents
    Currency string
}

// By giving Money a String() method, we satisfy fmt.Stringer.
// fmt.Println(m) will now call this method.
func (m Money) String() string {
    return fmt.Sprintf("%s %.2f", m.Currency, float64(m.Amount)/100)
}

func main() {
    price := Money{Amount: 1999, Currency: "USD"}
    fmt.Println(price)               // USD 19.99
    fmt.Printf("paid %v\n", price)   // paid USD 19.99
}

We never imported fmt.Stringer. We never wrote Money implements Stringer. We just defined a method with the right name and signature, and the fmt package's runtime check found us. This is implicit satisfaction at work.

Try it: 1. Run the example. Confirm both prints show USD 19.99.

1. Comment out the String() method. Re-run. Now fmt.Println(price) prints {1999 USD} - the default struct formatting. The fmt package looked for Stringer, didn't find it, fell back.

2. Define type Username string with a String() method that returns "@" + string(u). Print one. Notice: a Username is a string underneath but Stringer controls how it prints.

The empty interface and any¶

There's a special interface that requires no methods:

type interface{}    // older spelling
type any            // Go 1.18+ alias; identical

Since every type has zero or more methods, every type satisfies interface{}. It's the type "anything at all." You'll see it used when a function needs to accept truly any value:

// fmt.Println's actual signature (simplified):
func Println(values ...any) (int, error)

Println takes any number of arguments of any type - int, string, your Money struct, all mixed together. It works internally by inspecting the dynamic type of each argument at runtime (see Going deeper for how).

any is what Go uses where other languages might say Object or void *. Two things to know:

1. Functions that take any lose all type information at the function boundary. Inside, you have to use type assertions or type switches (next section) to get back to a concrete type before you can do anything useful.

2. Prefer specific interfaces over any. func writeTo(w io.Writer) is much better than func writeTo(x any) - the first tells the reader (and the compiler) what's expected. Reach for any only when you genuinely accept anything.

Try it:

1. Define func describe(v any) { fmt.Printf("type=%T value=%v\n", v, v) }. Call it with an int, a string, and your Money struct. The %T verb prints the dynamic type.

2. Note that you can't do v + 1 inside describe - even if you pass an int. The compiler doesn't know it's an int once it's in a any slot. You'd have to assert (next section).

Type assertions and type switches¶

When you have an interface value and you want to get back to the concrete type underneath, you use a type assertion:

var v any = "hello"
s := v.(string)                  // type assertion: "treat v as a string"
fmt.Println(s, len(s))           // hello 5

v.(string) reads "give me v's underlying value, asserting it's actually a string." If v really is a string, you get it. If it isn't, the program panics.

The safer comma-ok form doesn't panic:

s, ok := v.(string)
if ok {
    fmt.Println("it's a string:", s)
} else {
    fmt.Println("not a string")
}

You've seen this shape before - same pattern as m["key"] returning (value, ok) on maps. The "comma ok" form is everywhere in Go.

For deciding among several types, use a type switch:

func describe(v any) {
    switch x := v.(type) {
    case nil:
        fmt.Println("it's nil")
    case int:
        fmt.Println("an int:", x*2)
    case string:
        fmt.Println("a string of length", len(x))
    case fmt.Stringer:
        fmt.Println("something stringer-able:", x.String())
    default:
        fmt.Printf("don't know: type=%T value=%v\n", v, v)
    }
}

Read the syntax carefully: switch x := v.(type) is special. The .(type) keyword (not a real type - a contextual keyword) is only legal inside a type switch. Each case is a type; inside that case, x has that type and can be used as such. case int: makes x an int; case fmt.Stringer: makes x a fmt.Stringer.

This is how fmt.Println actually dispatches: a type switch that checks for Stringer, error, []byte, and many others in some order.

Try it: 1. Type the describe example. Call it with 42, "hi", your Money, and nil. Each case fires. 2. The order of cases matters when types overlap. Try putting case fmt.Stringer: before case int:. What happens with describe(42)? (Hint: int doesn't have a String() method, so it's still not a Stringer. But other types might match earlier than you expect.) 3. Add case []int: and case map[string]int:. Test with appropriate values. Type switches handle complex types just fine.

Constructors (a convention, not a feature)¶

Go has no special "constructor" keyword. The convention is to write a regular function that returns a value of your type, named NewYourType:

func NewPerson(name string, age int) Person {
    return Person{Name: name, Age: age, City: "unknown"}
}

// Use it:
alice := NewPerson("Alice", 30)

This is just a function. The pattern gives you somewhere to put validation, defaults, or setup logic. Look for NewX functions in any Go library - they're everywhere.

type Speaker interface { Speak() string }

type Cat struct{ Name string }
func (c *Cat) Speak() string { return c.Name + " says meow" }  // pointer receiver

var s Speaker
s = &Cat{Name: "Whiskers"}    // OK - *Cat satisfies Speaker
s = Cat{Name: "Whiskers"}     // COMPILE ERROR - Cat does not satisfy Speaker
                              //   (Speak has pointer receiver)

p := Point{X: 3, Y: 4}
dist := p.DistanceFromOrigin    // method value: a function bound to p
fmt.Println(dist())             // 5

dist := Point.DistanceFromOrigin     // method expression: a free function
fmt.Println(dist(Point{X: 3, Y: 4})) // 5

p := Point{X: 3, Y: 4}
d := p.DistanceFromOrigin
p.X = 99
fmt.Println(d())       // still 5 - d captured a copy of p

type Logger struct {
    prefix string
}

func (l *Logger) Log(msg string) {
    fmt.Println(l.prefix + ": " + msg)
}

// Job embeds *Logger as an anonymous field. Logger's methods are "promoted"
// to Job - callers can do job.Log() as if Job had defined Log itself.
type Job struct {
    *Logger              // anonymous (embedded) field
    Command string
}

func main() {
    j := &Job{
        Logger:  &Logger{prefix: "Job"},
        Command: "build",
    }
    j.Log("starting")     // calls Logger.Log via promotion
                          // prints: Job: starting
}

// A function type with a method - so a plain function can satisfy http.Handler.
type HandlerFunc func(http.ResponseWriter, *http.Request)

func (f HandlerFunc) ServeHTTP(w http.ResponseWriter, r *http.Request) {
    f(w, r)
}

// Now any function with the right signature can be wrapped:
http.Handle("/hi", http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
    fmt.Fprintln(w, "hi")
}))

interface value (iface):
┌──────────────┬──────────────┐
│ itab pointer │ data pointer │
└──────┬───────┴──────────────┘
       │
       ▼
   itab:
   { interface type info
     concrete type info
     [func pointer for method 1]
     [func pointer for method 2]
     ... }

s.itab->fun[0](s.data)        // method 0 = Speak; first arg = the underlying value

import (
    "fmt"
    "unsafe"
)

type Greeter interface{ Greet() string }
type Person struct{ Name string }
func (p Person) Greet() string { return "Hi, " + p.Name }

func main() {
    var g Greeter = Person{Name: "Ada"}
    fmt.Println(unsafe.Sizeof(g))         // 16 - two words
    fmt.Println(g.Greet())                // Hi, Ada
    fmt.Printf("%T\n", g)                 // main.Person - itab told us the type
}

type MyError struct{ Code int }
func (e *MyError) Error() string { return "boom" }

func mightFail() error {
    var e *MyError              // e is a typed nil: type=*MyError, value=nil
    return e                    // returned as a non-nil interface!
}

func main() {
    err := mightFail()
    if err != nil {             // TRUE - even though e was nil
        fmt.Println("got an error:", err)
    }
}

func mightFail() error {
    var e *MyError
    if everythingFine {
        return nil              // untyped nil - interface really is nil
    }
    e = &MyError{Code: 42}
    return e
}

func mightFail() error {
    if everythingFine {
        return nil
    }
    return &MyError{Code: 42}    // no chance of accidentally returning typed nil
}

// Good: accepts a small interface, returns a concrete type.
func WriteHeader(w io.Writer, name string) (*Header, error) {
    _, err := fmt.Fprintf(w, "X-Source: %s\r\n", name)
    if err != nil {
        return nil, err
    }
    return &Header{Name: name}, nil
}

// Less good: accepts a concrete type (over-specified), returns an interface (under-specified).
func WriteHeader(w *os.File, name string) (io.ReadCloser, error) { ... }

type MyHandler struct{ ... }
func (h *MyHandler) ServeHTTP(w http.ResponseWriter, r *http.Request) { ... }

// Compile-time check: *MyHandler must satisfy http.Handler.
// The variable is named _ so it's discarded.
var _ http.Handler = (*MyHandler)(nil)

// A constraint: "any type whose underlying type is int, int32, int64, or float64".
type Number interface {
    ~int | ~int32 | ~int64 | ~float64
}

// A generic function constrained by Number.
func Sum[T Number](values []T) T {
    var sum T
    for _, v := range values {
        sum += v
    }
    return sum
}

func main() {
    fmt.Println(Sum([]int{1, 2, 3}))           // 6
    fmt.Println(Sum([]float64{1.5, 2.5}))      // 4
}

Exercise¶

In a new file shapes.go:

1. Define a struct Rectangle with two float64 fields: Width and Height.

2. Add two methods on Rectangle:

3. Area() float64 - returns Width * Height.

4. Perimeter() float64 - returns 2 * (Width + Height).

5. In main, create a Rectangle with width 5 and height 3. Print its area and perimeter. (Expected: 15 and 16.)

6. Write a regular function LargerOf(a, b Rectangle) Rectangle that returns whichever rectangle has the bigger area. Test it with two rectangles of different sizes.

7. Add a constructor NewSquare(side float64) Rectangle that returns a Rectangle with both fields set to side. Test it: NewSquare(4).Area() should be 16.

Now extend it with an interface:

1. Define a Circle struct with one float64 field Radius. Add methods Area() float64 (returns π·r²; use math.Pi) and Perimeter() float64 (returns 2π·r).

2. Define a Shape interface that requires both Area() float64 and Perimeter() float64.

3. Write a function Describe(s Shape) that prints "area=X, perimeter=Y". It should accept any type satisfying Shape - both Rectangle and Circle work.

4. Call Describe(Rectangle{Width: 5, Height: 3}). Then call Describe(Circle{Radius: 4}). The same function handles both.

5. Stretch: add a String() string method to Rectangle that returns "Rect(WxH)". Now fmt.Println(r) uses it automatically - because Rectangle satisfies fmt.Stringer implicitly.

6. Stretch: add a compile-time check at the top of the file:

   var (
       _ Shape         = Rectangle{}
       _ Shape         = Circle{}
       _ fmt.Stringer  = Rectangle{}
   )
   

   Try removing the Area() method from Circle. The compiler tells you exactly where the contract broke.

What you might wonder¶

"Why uppercase field names?" In Go, capitalizing a name makes it visible from outside the package (other people's code can see it). Lowercase keeps it private to the current package. You'll meet packages properly in page 11. For now: capital is the safer default.

"What's the difference between a struct and a class?" If you've used a language with classes (Java, Python, C++): a Go struct is similar but smaller. No inheritance. No constructors built in. Methods are attached separately (not inside the type declaration). Go gets away with this minimalism because interfaces (which you met above) handle the cases other languages use inheritance for - and they do it in a more flexible way, because satisfaction is implicit instead of declared.

"Can I have a struct that contains another struct?" Yes. Very common. A Person could contain an Address field of type Address. Field access chains: p.Address.Street.

"What's the zero value of a struct?" If you write var alice Person without initializing fields, every field gets its zero value - 0 for numbers, "" for strings, false for booleans, nil for the things we haven't met yet. Useful: a fresh Person is always valid-looking, not garbage.

Done¶

You can now: - Define your own types with type Name struct { ... } (and on non-struct types too). - Create struct values with the Type{Field: value, ...} literal. - Read and write fields with dot notation. - Pass structs to functions and return them. - Attach methods to types with a receiver. - Choose between value and pointer receivers (modification → pointer). - Define an interface that captures a behavior - and pass any type with the right methods through it. - Use the empty interface (any) when you genuinely accept anything. - Recover a concrete type from an interface value with type assertions or type switches.

You can now model things that have multiple properties and write code that works against contracts rather than against specific types. Combined with what came before, you can build programs that are both data-rich and flexible enough to test, swap implementations, and grow without rewriting.

Next page: how Go handles collections - lists of things, lookups by key. Slices and maps.

Next: Many things at once → 06-slices-and-maps.md

06 - Many Things at Once¶

What this session is¶

About an hour. You'll learn the two most-used "collection" types in Go: slices (an ordered list of things, like a shopping list) and maps (a lookup table, like a dictionary where you look up a word to find its meaning). Almost every real Go program uses both, constantly.

Why you need these¶

Until now, every variable has held one thing. One name. One age. One person. Real programs deal with many things. A list of users. A count of how many times each word appears in a document. The temperatures for each day of the week. You need types built for collections.

Go gives you three: arrays, slices, and maps. Slices and maps are what you'll actually use. Arrays exist, but you'll see them rarely - we'll mention them only enough to recognize them.

Slices: ordered lists¶

package main

import "fmt"

func main() {
    names := []string{"Alice", "Bob", "Chioma"}
    fmt.Println(names)
    fmt.Println(names[0])      // Alice - slices are 0-indexed
    fmt.Println(names[2])      // Chioma
    fmt.Println(len(names))    // 3
}

Type and run.

What's new:

• []string{...} - a slice of strings. The [] says "a list of"; string says "of strings".
• names[0] - read the first element. Indexing starts at 0, not 1. (names[2] is the third element.)
• len(names) - built-in function that gives the number of elements.

Common mistake: going off the end. names[3] would crash the program (Go calls this a "panic" - we'll meet it later). Always know how many elements you have before indexing.

What a slice actually is (the mental model)¶

Here's what surprises people: a slice in Go is not a list. It's a tiny three-field struct that describes a list living elsewhere in memory.

The three fields:

slice header:
┌─────────┬─────┬─────┐
│ pointer │ len │ cap │
└────┬────┴─────┴─────┘
     │
     ▼
backing array:  [ A ][ B ][ C ][ D ][ E ]

• pointer - where the elements actually live in memory.
• length - how many elements the slice currently uses (what len(s) returns).
• capacity - how big the underlying array is from the pointer onward (what cap(s) returns).

When you write s := []int{1, 2, 3}, Go allocates an array of 3 ints somewhere, then makes a slice header pointing at it: {ptr → [1 2 3], len=3, cap=3}.

You can see all three with the built-in cap function:

s := []int{1, 2, 3}
fmt.Println(len(s), cap(s))   // 3 3

The big consequence: when you pass a slice to a function, you copy the header - three small fields. You do not copy the elements. The function and the caller end up with two slice headers pointing at the same underlying array. Writes through one header are visible through the other. We'll come back to this in Going deeper.

Try it: 1. Type the program above and add s = append(s, 4). Print len(s) and cap(s) again. What changed?

1. Try t := make([]int, 3, 10). What do len(t) and cap(t) show? What does t actually contain before you write to it?

Adding to a slice: append¶

Slices grow:

names := []string{"Alice", "Bob"}
names = append(names, "Chioma")
fmt.Println(names)   // [Alice Bob Chioma]

append(slice, value) returns a new slice with the value added. You almost always reassign back to the same variable: names = append(names, "Chioma").

Two notes that will save you confusion later:

1. append returns a value; it doesn't change the slice in place. Forgetting the names = part is a common bug - your append does nothing visible.

2. You can append several values: append(names, "D", "E", "F").

The growing-array story. When you append, Go does one of two things:

• There's room (cap > len): write into the existing backing array, return a slice header with len bumped by one. Fast.
• There's no room (cap == len): allocate a new, bigger backing array, copy the old elements in, write the new element, return a slice header pointing at the new array. The old array is left to the garbage collector.

That's why we always reassign: names = append(names, ...). The header you get back may point at a different array than the one you passed in.

Watch it happen:

s := []int{}
for i := 0; i < 10; i++ {
    s = append(s, i)
    fmt.Printf("len=%2d cap=%2d\n", len(s), cap(s))
}

You'll see capacity jump in chunks (e.g., 1 → 2 → 4 → 8 → 16), not grow by one each time. Go roughly doubles capacity when it reallocates, so a million appends don't take a million allocations - they take about twenty. We'll see the exact growth strategy in Going deeper.

Try it: 1. Run the loop above. Note the capacities you see.

1. Change 10 to 100. Watch the jumps. Does the doubling slow down at any point?

2. Add fmt.Println("pointer:", &s[0]) just after s = append(...). When the pointer changes, you know a reallocation just happened.

Looping over a slice: range¶

You've seen for i := 0; i < len(names); i++ style loops on page 03. For slices, there's a friendlier form:

for i, name := range names {
    fmt.Println(i, name)
}

Output:

0 Alice
1 Bob
2 Chioma

range names gives you two values per iteration: the index and the value at that index. If you don't need the index, use _:

for _, name := range names {
    fmt.Println(name)
}

The underscore _ means "I don't care about this." Go won't compile if you create a variable and don't use it (page 02) - _ is the official way to say "throw this away."

A slice of structs¶

Combine what you know:

type Person struct {
    Name string
    Age  int
}

people := []Person{
    {Name: "Alice", Age: 30},
    {Name: "Bob", Age: 25},
    {Name: "Chioma", Age: 35},
}

for _, p := range people {
    fmt.Println(p.Name, "is", p.Age)
}

A slice can hold any type - structs you defined, other slices, anything.

Strings are almost slices¶

A Go string is structurally like a slice header without the capacity: a pointer to bytes plus a length. The pointer-to-bytes points at immutable memory - you can't change a character in place. Everything else works like you'd expect.

s := "hello"
fmt.Println(len(s))    // 5
fmt.Println(s[0])      // 104  -- the byte 'h', not the character!

Two surprises live here.

len(s) is bytes, not characters. A Go string is a sequence of bytes (which may be UTF-8 text). For ASCII text (English, code, numbers), bytes and characters line up - len("hello") is 5. For non-ASCII characters, one character can take multiple bytes:

s := "café"
fmt.Println(len(s))    // 5  -- not 4!  ('é' is two bytes in UTF-8)

s[0] gives you a byte, not a character. That's why fmt.Println(s[0]) printed 104 - the byte value of 'h'. To work with characters (Go calls them runes - Unicode code points stored as int32), use range:

s := "café"
for i, r := range s {
    fmt.Printf("byte %d: rune %c (%U)\n", i, r, r)
}

Output:

byte 0: rune c (U+0063)
byte 1: rune a (U+0061)
byte 2: rune f (U+0066)
byte 3: rune é (U+00E9)

range over a string decodes UTF-8 for you. Each iteration gives the byte offset of the rune (so the index can jump by 1, 2, or 3 depending on the rune's width), plus the rune itself as an int32. This is the only place in Go where the language treats UTF-8 specially.

You can slice a string just like a slice - s[1:3] - but you're slicing bytes, not characters. "café"[3:] returns the last two bytes (which together encode é); "café"[3:4] returns the first half of é and is not valid UTF-8. String slicing only makes sense at known rune boundaries.

The fast way to count actual characters:

import "unicode/utf8"

s := "café"
fmt.Println(len(s))                       // 5  (bytes)
fmt.Println(utf8.RuneCountInString(s))    // 4  (runes/characters)

Try it: 1. Run the range example with s := "日本語" (Japanese for "Japanese language"). Each rune is 3 bytes - predict the byte offsets before you run it.

1. Print len("日本語") and the count from a for range loop. They'll differ.

2. Try fmt.Println("café"[3:4]). You'll see a single byte that's not valid on its own. Now try fmt.Println("café"[3:5]) - that's the full é.

Maps: looking things up by key¶

A map is a collection where each entry has a key (the thing you look up by) and a value (the thing you get back).

package main

import "fmt"

func main() {
    ages := map[string]int{
        "Alice":  30,
        "Bob":    25,
        "Chioma": 35,
    }

    fmt.Println(ages["Alice"])    // 30
    fmt.Println(ages["Bob"])      // 25
    fmt.Println(len(ages))        // 3
}

What's new:

• map[string]int{...} - a map whose keys are strings and whose values are ints. Read it as "a map FROM string TO int."
• ages["Alice"] - look up the value for the key "Alice".

Add or update an entry:

ages["Dimeji"] = 40   // adds a new entry
ages["Alice"] = 31    // updates Alice's age

Delete an entry:

delete(ages, "Bob")

What a map actually is (the mental model)¶

A map in Go is a pointer to a hash table.

That short sentence packs three useful facts:

1. It's a pointer. When you pass a map to a function, you're passing a small pointer-sized value. The function operates on the same underlying table. Modifications stick - there's no "pass a copy" the way you'd get with a struct.

2. It's a hash table. Lookups, inserts, and deletes are amortized O(1) - the cost doesn't grow with how much is in the map. Go hashes the key, finds the right slot, and does the operation.

3. The variable can be nil. Maps must be initialized before you write to them, or your program panics.

var m map[string]int       // nil map
fmt.Println(m["anything"]) // 0     -- reading a nil map is OK
m["new"] = 1               // PANIC: assignment to entry in nil map

Always create a map with make or a literal:

m := make(map[string]int)              // empty, ready to use
m := map[string]int{"a": 1, "b": 2}    // empty + initial entries

Because a map is a pointer, sharing one between functions is cheap and side effects are visible:

func addOne(scores map[string]int, k string) {
    scores[k] = scores[k] + 1
}

func main() {
    scores := map[string]int{"alice": 0}
    addOne(scores, "alice")
    addOne(scores, "alice")
    fmt.Println(scores["alice"])    // 2
}