Packages, Modules & Layout

"Every module is characterized by its knowledge of a design decision which it hides from all others." — David L. Parnas, On the Criteria To Be Used in Decomposing Systems into Modules (1972)

Everything so far has been about making code work. This Part is about what a codebase needs beyond that — and it opens with the decision that shapes every other one, because it is the hardest to change later.

Parnas wrote the sentence above in 1972, arguing against the way everyone was decomposing systems at the time: by processing step, so that each module was one box on the flowchart. His alternative was to split by what varies — each module owns a decision that might change, and hides it, so a change to that decision touches one place. Fifty years of software architecture is largely rediscovery of that paragraph, and Go's package system is one of the more direct implementations of it.

Go adds an unusual amount of enforcement. A package is a compilation unit with a genuine boundary: identifiers starting with a capital letter are visible outside it and the rest are not, checked by the compiler rather than by convention. Import cycles are a compile error, not a code smell. And internal/ makes "this is ours, not yours" a rule the toolchain enforces against people who have never read your documentation.

A package is a boundary, not a folder

The most common structural mistake in Go is grouping by kind — a models package, a handlers package, a utils package — which produces boundaries that no design decision lives behind.

The test that works is Parnas's: what does this package know that nobody else needs to? A store package knows how records are persisted. A billing package knows what a charge is worth. Those hide decisions. A models package hides nothing — it is a folder of types every other package must import, so it becomes a hub that everything depends on and that can never change.

That leads directly to the second question, which is which way the arrows point.

Store exports a concrete type. The consumer declares the one-method interface it actually uses, and Store satisfies it without knowing the interface exists — which is what Part I's chapter on implicit satisfaction was building toward, seen now as an architectural tool rather than a language curiosity.

This inverts the habit most people bring from other languages, where an interface is declared next to its implementation and the consumer imports it. Three things follow from doing it Go's way.

The dependency arrow points from the consumer to the concrete type, and never back. Store imports nothing from describe's package, so there is no cycle to create.

The interface is as small as the caller needs. getter has one method because that is all describe uses. A producer-side interface always grows to the union of everything anyone might want, and then every implementation must satisfy all of it.

Test doubles need no coordination. fakeGetter satisfies getter by having the right method. Nobody had to plan for it.

Hence the proverb: accept interfaces, return structs. Return the concrete type so callers get everything; accept the narrowest interface so callers can substitute.

What runs when your package is loaded

Before main executes, Go initialises every package it depends on, and the order is more precisely defined than most people realise.

Package-level variables are initialised in dependency order, not source order: total is written first and initialised last, because it needs the other two. Go works this out from the reference graph, and a cycle among package variables is a compile error for the same reason an import cycle is.

Then every init() runs, in source order, and only then does main start. Across packages, imports are fully initialised before the importer, so by the time your init runs, everything you import is ready.

All of which is precisely specified, and mostly a reason to use less of it.

init() is code that runs before anyone asks for it. It cannot take arguments, cannot return an error, and cannot be called from a test to set up state or skipped to avoid it. A failure inside one leaves panic or log.Fatal as the only options, which turns a recoverable configuration problem into a process that cannot start.

The legitimate uses are narrow: registering something with a registry (database/sql drivers, image format decoders), building a lookup table that cannot be a literal, and compiling a package-level regexp.MustCompile. What does not belong is anything that can fail for reasons outside your source code — reading files, opening connections, parsing environment variables. Those want an explicit New that returns (*T, error), so the caller decides when it happens and what to do when it does not work.

The same argument applies to package-level vars doing real work. var db = mustConnect() runs at import time, in a test binary, in a go vet run, in a build tool that only wanted your type definitions — and there is no way to opt out.

Modules, versions, and the surface you commit to

A module is a collection of packages versioned together — the unit you publish and depend on. One go.mod at its root names it and lists its requirements:

// Not runnable here — the playground compiles a single file, with no module.
module github.com/acme/billing

go 1.22

require (
    github.com/google/uuid v1.6.0
    golang.org/x/sync v0.7.0
)

The module path is also the import prefix, so a package in internal/ledger is imported as github.com/acme/billing/internal/ledger. That coupling of identity to location is why the path is worth choosing carefully: changing it later is a breaking change for everyone.

What matters day to day is not the file but what it commits you to — because once tagged v1.0.0, every exported identifier in every non-internal package is API you have promised to keep.

That is Part III's error-surface argument arriving as a versioning argument. ErrNotFound is a commitment; errBackendUnreachable can be renamed, split or deleted in a patch release because it is unreachable by name. The capital letter is the whole difference.

Three module facts worth carrying:

internal/ is enforced by the compiler. A package under internal/ may only be imported by code rooted at that directory's parent. It is the one way to publish a module while keeping most of it genuinely private, and it is the right default for anything you are not ready to promise.

Minimal version selection means your build does not drift. The version you get is the oldest that satisfies every requirement, so adding one dependency never silently upgrades another. Upgrades happen when you run go get -u, and not otherwise.

go.sum is not a lock file. It records cryptographic hashes of the exact module contents used, so a tampered or re-tagged dependency fails the build. go.mod decides versions; go.sum verifies bytes.

The layout arguments worth ignoring

Go has no official project layout, which has produced more argument than the language deserves. The genuinely load-bearing conventions are short:

// Not runnable here — this is a directory tree, not a program.
billing/
├── go.mod                 // module root
├── cmd/
│   ├── api/main.go        // one binary per directory under cmd/
│   └── worker/main.go
├── internal/              // compiler-enforced: importable only within this module
│   ├── ledger/
│   └── postgres/
├── ledger.go              // the module's own public API, at the root
└── ledger_test.go         // tests live beside the code they test

cmd/ holds executables, one directory per binary, and each main should be thin — parse flags, build dependencies, call into a package that does the work. A main package cannot be imported, so anything it contains cannot be tested from elsewhere or reused.

The technique that makes that concrete is worth its own block, because it costs three lines and changes what is testable:

run takes its arguments and its output as parameters rather than reaching for os.Args and os.Stdout directly, and it returns an error rather than calling os.Exit. That is the entire trick: a test can pass a strings.Builder and assert on the bytes, and can assert on the error without the test binary exiting. main keeps the two things that genuinely cannot be tested — reading the real argument list and setting the exit status — and nothing else.

internal/ is a real mechanism, not a naming convention, and it is the most under-used thing in Go project structure. Everything starts there; things graduate out when you decide to support them.

Tests live beside the code, in the same directory, named _test.go. There is no parallel test tree.

Then there is pkg/, which is the argument. It comes from a popular unofficial "standard layout" repository and means "the public bits" — which is exactly what internal/ already expresses, in reverse and with compiler enforcement. It adds a path segment to every import and communicates nothing the absence of internal/ did not. The Go team has never used it in the standard library or their own projects. Skip it, and skip most of what that repository recommends: it describes conventions from large enterprise codebases as though they were requirements, and applying them to a service with four packages produces a directory tree deeper than the code is tall.

The real rule is that structure should follow the code, not precede it. Start flat, in one package at the module root. Split when a boundary becomes obvious — when you notice a set of files that change together and know something the rest does not. A codebase of eleven files in one package is easy to reorganise; the same code pre-split across nine packages you designed on day one is not.

Package-level state is a dependency you cannot see

A package-level variable holding real state is a dependency that never appears in a signature, and it is the quiet reason a lot of Go code is hard to test.

Clock is the whole technique: name the dependency as a type, take it in the constructor, default it when the caller does not care. The production path is unchanged and the test path becomes possible — and the signature now says what this type needs, which package-level state never does.

This generalises to almost everything usually made global. A logger, a database handle, a config struct, an HTTP client, a metrics registry: each is a dependency, and each is better as a struct field set by a constructor. The costs of the global version are consistent — tests cannot run in parallel because they share it, initialisation order becomes load-bearing, and nothing in any signature reveals the coupling.

The standard library's own use of package-level state is instructive here, because it is mostly a warning. http.DefaultServeMux and http.DefaultClient are globals, and the advice from the Go team is to avoid both: DefaultServeMux means any imported package can register a route on your server, and DefaultClient has no timeout, so a hung request hangs forever. Both exist because they made the tutorial shorter, and both are things production code replaces.

Common Mistakes

1. Packages named by kind — models, utils, helpers, common. They hide no decision, so they become hubs that everything imports and nothing can change.

2. Declaring an interface next to its implementation. Producer-side interfaces grow to the union of every caller's needs. Let the consumer declare the narrow interface it uses.

3. Returning an interface from a constructor. Callers lose access to everything the concrete type offers. Accept interfaces, return structs.

4. Doing real work in init() or a package-level var. It runs before anyone asked, cannot fail gracefully, and cannot be skipped by a test. Use New that returns (*T, error).

5. Exporting by default. Every capital letter in a tagged module is permanent. Start lowercase, start under internal/, and export when a caller actually needs it.

6. Not using internal/. It is compiler-enforced privacy across an entire subtree, and it is the cheapest way to keep options open.

7. Adopting pkg/. It duplicates what the absence of internal/ already says, adds a path segment to every import, and is used by neither the standard library nor the Go team.

8. Splitting into packages before the boundaries are known. Eleven files in one package are easy to reorganise; nine packages designed on day one are not.

9. Fixing an import cycle with a types package. It relocates the problem into a package with no owner, which then becomes a magnet that everything imports. The cycle means the boundary is wrong.

10. Package-level state instead of injected dependencies. It is a dependency invisible in every signature, it blocks parallel tests, and it makes initialisation order load-bearing.

Interview Corner

Hands-on

Summary

• A package should hide a decision, in Parnas's sense. If you cannot name what it hides, you have made a folder — which is why models, utils and common become hubs that can never change.
• Declare interfaces where they are consumed, as small as the caller needs. Producer-side interfaces grow to the union of everyone's requirements.
• Accept interfaces, return structs. Callers keep every method of the concrete type, and can still substitute at the boundary.
• Package variables initialise in dependency order, then every init() in source order, then main.
• Avoid real work in init() and package-level vars. It runs before anyone asked, cannot return an error, and cannot be skipped by a test. Prefer New() (*T, error).
• Every exported identifier in a tagged module is permanent. Start lowercase, start under internal/, and export when a caller genuinely needs it.
• internal/ is compiler-enforced privacy across a whole subtree, and it is the most under-used mechanism in Go project structure.
• Skip pkg/. It says what the absence of internal/ already says, adds a path segment, and neither the standard library nor the Go team uses it.
• An import cycle means the boundary is wrong, not that you need a types package — extracting one relocates the problem into a package nobody owns.
• Package-level state is a dependency invisible in every signature. Name it as a type, take it in the constructor, default it when the caller does not care.

Structure decides where code lives; the next chapter decides whether it works. Go's testing story is unusually good, and unusually plain — no assertion library, no annotations, no separate test tree, just a _test.go file and functions taking *testing.T. The next chapter is table-driven tests and the tooling around them: subtests and what t.Run buys you, t.Parallel and the trap inside it, testing.TB for shared helpers, golden files, fuzzing, and the reason go test -race belongs in every CI pipeline in the language.