← rhash

Go — Lesson 1: Your First Go Run

Learning track

The lab terminal is a high-fidelity simulation of the Go toolchain — go run, go build, gofmt, and go vet behave like the real commands for everything in this lesson. Real Go is a free download from go.dev; this lesson needs no install and no account.

Lesson 1 · Assumes you can already program — just not in Go

Toolchain, Module, Binary

Every lesson in this track grows one real project: linkstash, a tool that saves links and finds them again. Today it is a bare command-line scaffold. Later lessons bolt on an HTTP API, concurrency, and persistence — and the track ends with you contributing to a real open-source Go project. Nothing is a throwaway snippet; every lesson leaves the project more real than it found it.

The pain Go was born from

In 2007, engineers at Google were building enormous server programs, and the tools fought them: builds that took the better part of an hour, a language so complex that no one held all of it in their head, and dependency management that felt like defusing a bomb. The multicore era had arrived, but their languages made concurrency painful enough that people avoided it.

Picture a workshop where every job starts with sharpening the tools for an hour. The craftspeople are skilled — the workshop itself is the bottleneck. Eventually someone asks: what if we designed the workshop around the work?

That question produced Go (often called Golang, after its old domain name). Go is a compiled, statically typed language designed at Google by Robert Griesemer, Rob Pike, and Ken Thompson. Its founding bet: a language for large teams and large codebases should be small — few features, fast builds, and concurrency built in rather than bolted on. Everything in this lesson is that bet made visible.

“Works on my machine” is a deployment bug

You already know this pain from other languages: the program runs perfectly on your laptop, then dies on the server because a runtime version differs, a library is missing, or an environment variable was never set. Deploying becomes archaeology.

Think of shipping furniture two ways. Flat-pack means the receiver needs the right tools, the right screws, and patience. Go ships the finished piece: one sealed box, nothing to assemble at the other end.

go build compiles your program — and the parts of the Go runtime it needs — into a single static binary. No interpreter to install, no dependency tree to recreate on the target machine. Copy one file, run it. You will produce exactly such a binary in the lab and execute it yourself.

Formatting wars are a tax on every code review

Every team you have worked with had style arguments: tabs or spaces, brace placement, import order. Those arguments burn review time that should go to logic, and they never truly end — they just get relitigated with each new hire.

Imagine a newsroom with exactly one stylebook, enforced by a tireless robot editor. Writers stop debating commas and argue about the story instead. Nobody loves every rule; everybody loves that the argument is over.

In Go, that robot is gofmt. There is one official format, gofmt applies it mechanically, and Go code in the wild all looks the same because of it. This is not a suggestion in Go culture — it is law. Unformatted code in a pull request marks you as a tourist before anyone reads your logic. From today: gofmt (and its stricter sibling in go vet) clean, always.

A project needs a manifest, not a magic directory

Early Go forced every project into one rigid workspace directory, and importing code depended on where it happened to live on your disk. Step outside that directory and the toolchain got confused. Real projects — with versions and dependencies — needed something better.

Think of the manifest you already trust in other ecosystems: package.json, requirements.txt, Cargo.toml. One small file at the project root that says “this is the project, this is its name, these are its dependencies.”

Go’s manifest is go.mod, and the project it describes is a module. You create it once with go mod init linkstash, and from then on the toolchain knows the project’s name and boundary no matter where the folder lives. The lab’s second task is exactly this command — and you’ll watch go.mod appear.

Mental model #1: your program ships with a manager

Here is the pain behind Go’s most famous feature. Operating-system threads are expensive: each reserves a large stack and is scheduled by the kernel. A server juggling ten thousand connections cannot afford ten thousand OS threads, so in other languages you contort code into callbacks and event loops to share a few threads by hand.

Picture an airport with a handful of runways and thousands of planes. The planes don’t each need a runway parked under them all day — a good tower rotates them through. Go’s runtime is that tower: a few OS threads (runways) multiplexed across many lightweight goroutines (planes), each with a tiny stack that grows only when needed.

The formal name is the goroutine scheduler, and it lives inside every Go binary as part of the runtime. Lesson 5 goes deep — channels, select, the race detector as a habit. Today, just plant the model: a Go program is never just your code; it is your code plus a small, smart manager that makes cheap concurrency possible. Every later lesson hangs on that sentence.

Errors that whisper are worse than errors that speak

In exception-based languages, a function can fail three calls deep and you find out at a catch far away — or never. The failure path is invisible in the code you’re reading, which is exactly where you needed to see it.

Think of a delivery driver who hands you the parcel and a condition report together. “Here’s your package — and the corner is dented, check it now.” Nothing is hidden; you decide on the spot what the damage means.

Go functions return errors as ordinary values, usually as the last of multiple return values. The idiom you will write thousands of times is:

text, err := banner()
if err != nil {
    // handle it — right here, where it happened
}
fmt.Println(text)

No hidden control flow. The error is a value you must consciously deal with, and if err != nil is Go’s most recognizable sentence. In the lab’s final task you will refactor linkstash’s main to use a banner() function with exactly this shape — the first law of idiomatic Go, practiced on day one.

The standard library is the textbook

Most languages hide their best code. Go’s standard library is famously readable, ships with the language, and its documentation is one command away — even offline. go doc fmt.Println prints the contract of the exact function you used today, written by the people who wrote Go.

Apprentice chefs learn by reading the master’s recipe cards, not just cookbooks about cooking. In this track, when a lesson leans on a standard-library package, we read its real docs with go doc — try it in the lab terminal any time.

The toolchain, on one screen

One program — go — drives the whole workflow, plus gofmt beside it. Learn this rhythm now; every lesson reuses it.

go versionAsk the toolchain who it is. The sanity check before anything else.
go mod initCreate the module — write the project’s manifest (go.mod).
go run .Compile and run in one step. Your inner loop while developing.
gofmt -wRewrite files in the one official format. Non-negotiable, always.
go vet ./...Static checks beyond compilation — suspicious constructs the compiler tolerates.
go buildProduce the single static binary you can copy anywhere and run.
go docRead the standard library’s own documentation, offline.
go testComing in Lesson 7 with table-driven tests — listed now so the rhythm is complete.

Init the module. Run it. Format it. Vet it. Build it. Keep that sentence in mind; you will perform it in the lab.

Where this track goes

  1. 1Your First Go Run — toolchain, modules, gofmt/vet law, errors as values. You are here.
  2. 2Values, Structs & Honest Errors — linkstash stores real links; types, zero values, wrapping errors.
  3. 3Interfaces, Satisfied Implicitly — the mental model behind Go’s quiet superpower.
  4. 4linkstash Becomes an HTTP API — net/http, read as the textbook it is.
  5. 5Goroutines & Channels — the scheduler model, put to work checking links in parallel.
  6. 6Context, select & the Race Detector — cancellation as a discipline; go test -race as a reflex.
  7. 7Persistence & Table-Driven Tests — linkstash survives a restart, proven by real tests.
  8. 8The Contribution Milestone — a real issue, a real codebase, a fix with tests, a pull request. The finish line is a maintainer’s review, not a certificate.