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

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"
)

Read references/imports-and-main.md for extended import grouping, proto pb suffixes, the run() pattern, and CLI flag conventions.

Avoid init()

When you must use init(), make it:

1. Deterministic — same result every run.
2. Independent of the order of other init()s.
3. Free of environment state (env vars, working dir, args).
4. Free of I/O (filesystem, network, syscalls).

Acceptable uses:

• Precomputing a constant that cannot fit in a single expression.
• Registering pluggable hooks (database/sql drivers).

If your init reads a file or calls a network API, refactor it into an explicit Setup() the caller invokes.

Exit Only in main

func main() {
    if err := run(); err != nil {
        log.Fatal(err)
    }
}

func run() error {
    // all the real work
    return nil
}

Why:

• log.Fatal and os.Exit skip defer. Anywhere except main, that means leaked files, half-flushed buffers, undeleted temp dirs.
• The run() pattern gives you one place to log a clean error and one place to set the exit code.

CLI Flags

• Define flags in package main.
• Flag names use snake_case: --output_dir, not --outputDir.
• Libraries accept configuration through function parameters, never reach for flag.Lookup.

func main() {
    outputDir := flag.String("output_dir", ".", "directory for output files")
    flag.Parse()
    if err := mylib.Generate(*outputDir); err != nil {
        log.Fatal(err)
    }
}

Read references/init-and-globals.md for the boundaries between safe init-time computation, mutable globals, and dependency injection.

Anti-Patterns

Verification Checklist

• [ ] Package name is concrete and unambiguous
• [ ] Imports are grouped (stdlib first), goimports clean
• [ ] No init() performs I/O or depends on env state
• [ ] main is a single if err := run(); err != nil { log.Fatal(err) }
• [ ] No os.Exit / log.Fatal* outside main
• [ ] Flags are defined only in package main
• [ ] No import . and no blank import outside main/tests
• [ ] Package's purpose fits in one sentence

References

• references/package-layout.md — splitting packages, cmd/, internal/, public API surface
• references/imports-and-main.md — extended import grouping, the run() pattern, flag conventions
• references/init-and-globals.md — when init is acceptable, mutable globals, DI