Go package organization, imports, and dependency management from Google and Uber style guides. Use when creating packages, organizing imports, managing dependencies, using init(), or deciding how to structure Go code into packages.
This skill covers package organization and import management following Google's and Uber's Go style guides.
Advisory: This is a best practice recommendation.
Package names should describe what the package provides. Avoid generic names
like util, helper, common, or similar—they make code harder to read and
cause import conflicts.
// Good: Meaningful package names
db := spannertest.NewDatabaseFromFile(...)
_, err := f.Seek(0, io.SeekStart)
// Bad: Vague package names obscure meaning
db := test.NewDatabaseFromFile(...)
_, err := f.Seek(0, common.SeekStart)
Generic names like can be used as of a name (e.g., ) but should not be the entire package name.
utilstringutilAdvisory: This is best practice guidance.
When to combine packages:
When to split packages:
bytes.Buffer, ring.NewFile organization: No "one type, one file" convention in Go. Files should be focused enough to know which file contains something and small enough to find things easily.
Normative: This is required per Go Wiki CodeReviewComments.
Imports are organized in groups, with blank lines between them. The standard library packages are always in the first group.
package main
import (
"fmt"
"hash/adler32"
"os"
"github.com/foo/bar"
"rsc.io/goversion/version"
)
Use goimports to manage this automatically.
Combined: Google + Uber guidance
Minimal grouping (Uber): stdlib, then everything else.
Extended grouping (Google): stdlib → other → protocol buffers → side-effects.
// Good: Standard library separate from external packages
import (
"fmt"
"os"
"go.uber.org/atomic"
"golang.org/x/sync/errgroup"
)
// Good: Full grouping with protos and side-effects
import (
"fmt"
"os"
"github.com/dsnet/compress/flate"
"golang.org/x/text/encoding"
foopb "myproj/foo/proto/proto"
_ "myproj/rpc/protocols/dial"
)
Normative: This is required per Go Wiki CodeReviewComments and Google's Go style guide.
Avoid renaming imports except to avoid a name collision; good package names should not require renaming. In the event of collision, prefer to rename the most local or project-specific import.
Must rename: collision with other imports, generated protocol buffer packages
(remove underscores, add pb suffix).
May rename: uninformative names (e.g., v1), collision with local variable.
// Good: Proto packages renamed with pb suffix
import (
foosvcpb "path/to/package/foo_service_go_proto"
)
// Good: urlpkg when url variable is needed
import (
urlpkg "net/url"
)
func parseEndpoint(url string) (*urlpkg.URL, error) {
return urlpkg.Parse(url)
}
import _)Normative: This is required per Go Wiki CodeReviewComments and Google's Go style guide.
Packages that are imported only for their side effects (using import _ "pkg")
should only be imported in the main package of a program, or in tests that
require them.
// Good: Blank import in main package
package main
import (
_ "time/tzdata"
_ "image/jpeg"
)
import .)Normative: This is required per Go Wiki CodeReviewComments and Google's Go style guide.
Do not use dot imports. They make programs much harder to read because it is
unclear whether a name like Quux is a top-level identifier in the current
package or in an imported package.
Exception: The import . form can be useful in tests that, due to circular
dependencies, cannot be made part of the package being tested:
package foo_test
import (
"bar/testutil" // also imports "foo"
. "foo"
)
In this case, the test file cannot be in package foo because it uses
bar/testutil, which imports foo. So the import . form lets the file
pretend to be part of package foo even though it is not.
Except for this one case, do not use import . in your programs.
// Bad: Dot import hides origin
import . "foo"
var myThing = Bar() // Where does Bar come from?
// Good: Explicit qualification
import "foo"
var myThing = foo.Bar()
Source: Uber Go Style Guide
Avoid init() where possible. When init() is unavoidable, code should:
init() functions// Bad: init() with I/O and environment dependencies
var _config Config
func init() {
cwd, _ := os.Getwd()
raw, _ := os.ReadFile(path.Join(cwd, "config.yaml"))
yaml.Unmarshal(raw, &_config)
}
// Good: Explicit function for loading config
func loadConfig() (Config, error) {
cwd, err := os.Getwd()
if err != nil {
return Config{}, err
}
raw, err := os.ReadFile(path.Join(cwd, "config.yaml"))
if err != nil {
return Config{}, err
}
var config Config
if err := yaml.Unmarshal(raw, &config); err != nil {
return Config{}, err
}
return config, nil
}
Acceptable uses of init():
database/sql dialects, encoding registries)Source: Uber Go Style Guide
Call os.Exit or log.Fatal* only in main(). All other functions should
return errors to signal failure.
Why this matters:
defer statements are skipped// Bad: log.Fatal in helper function
func readFile(path string) string {
f, err := os.Open(path)
if err != nil {
log.Fatal(err) // Exits program, skips defers
}
b, err := io.ReadAll(f)
if err != nil {
log.Fatal(err)
}
return string(b)
}
// Good: Return errors, let main() decide to exit
func main() {
body, err := readFile(path)
if err != nil {
log.Fatal(err)
}
fmt.Println(body)
}
func readFile(path string) (string, error) {
f, err := os.Open(path)
if err != nil {
return "", err
}
b, err := io.ReadAll(f)
if err != nil {
return "", err
}
return string(b), nil
}
Prefer to call os.Exit or log.Fatal at most once in main(). Extract
business logic into a separate function that returns errors.
// Good: Single exit point with run() pattern
func main() {
if err := run(); err != nil {
log.Fatal(err)
}
}
func run() error {
args := os.Args[1:]
if len(args) != 1 {
return errors.New("missing file")
}
f, err := os.Open(args[0])
if err != nil {
return err
}
defer f.Close() // Will always run
b, err := io.ReadAll(f)
if err != nil {
return err
}
// Process b...
return nil
}
Benefits of the run() pattern:
main() function with single exit pointdefer statements always execute| Topic | Rule | Type |
|---|---|---|
| Import organization | std first, groups separated by blank lines | Normative |
| Import grouping | std → other (→ proto → side-effect) | Combined |
| Import renaming | Only when necessary; prefer renaming local/project import | Normative |
| Blank imports | Only in main packages or tests | Normative |
| Dot imports | Only for circular test dependencies | Normative |
| Util packages | Avoid; use descriptive names | Advisory |
| Package size | Balance cohesion vs. distinct concepts | Advisory |
| init() | Avoid; must be deterministic if used | Advisory |
| Exit in main | Only exit from main(); return errors | Advisory |
go-style-corego-naminggo-error-handlinggo-defensivego-linting