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](references/package-layout.md) when deciding how to split a growing package, organizing `cmd/`, `internal/`, or designing a library API surface. ## Naming Packages ``...