go-packages

Go Packages and Imports

A package is a unit of meaning, not a folder of files. Name it for what it provides, keep imports tidy, and put startup logic where it belongs.

Core Rules

1. Package names describe what the package provides. util, helper, common, misc are not names.
2. Imports are grouped: stdlib first, then external. goimports will keep this honest.
3. Avoid init() — and when unavoidable, keep it deterministic and I/O-free.
4. os.Exit / log.Fatal only inside main. Library code returns errors.
5. Use the run() pattern so main has a single exit point and deferred cleanup runs.
6. CLI flags belong in package main. Libraries take configuration as parameters.
7. Blank imports belong in main or tests. Dot imports are essentially never appropriate.

Decision: How to Split a Package

Question	If "yes"
Can you state the package's purpose in one sentence?	Probably right-sized
Do its files never share unexported symbols?	Likely two packages glued by directory
Do distinct caller groups touch distinct files?	Split along caller boundaries
Is the godoc index so long callers cannot find things?	Split for discoverability
Does splitting create import cycles?	Don't split

Read references/package-layout.md when deciding how to split a growing package, organizing cmd/, internal/, or designing a library API surface.

Naming Packages

// Good — meaningful
db := spannertest.NewDatabaseFromFile(...)
_, err := f.Seek(0, io.SeekStart)

// Bad — vague
db := test.NewDatabaseFromFile(...)
_, err := f.Seek(0, common.SeekStart)

Generic words may appear as part of a name (stringutil, iotest) but not as the whole name. Match the package to a concept the caller already knows.

Imports

import (
    "fmt"
    "os"

    "github.com/foo/bar"
    "rsc.io/goversion/version"
)

Rule	Guidance
Group order	stdlib, then external; extended order may also separate protos and side-effect imports
Renaming	Avoid unless there is a collision; rename the more-local import
Blank import (import _)	Only main and tests
Dot import (import .)	Effectively never; rare in test files for circular deps