Go Packages and Imports

This skill covers package organization and import management following Google's and Uber's Go style guides.

Package Organization

Avoid Util Packages

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

util

can be used as part of a name (e.g.,

stringutil

) but should not be the entire package name.

Package Size

Advisory: This is best practice guidance.

When to combine packages:

If client code likely needs two types to interact, keep them together
If types have tightly coupled implementations
If users would need to import both packages to use either meaningfully

When to split packages:

When something is conceptually distinct
The short package name + exported type creates a meaningful identifier:
```
bytes.Buffer
```
,
```
ring.New
```

File 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.

Imports

Import Organization

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.

Import Grouping (Extended)

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

Import Renaming

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

Blank Imports (

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

Dot Imports (

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

Avoid init()

Source: Uber Go Style Guide

Avoid

init()

where possible. When

init()

is unavoidable, code should:

Be completely deterministic, regardless of program environment
Avoid depending on ordering or side-effects of other
```
init()
```
functions
Avoid global/environment state (env vars, working directory, args)
Avoid I/O (filesystem, network, system calls)

// 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():

Complex expressions that cannot be single assignments
Pluggable hooks (e.g.,
```
database/sql
```
dialects, encoding registries)
Deterministic precomputation

Exit in Main

Source: Uber Go Style Guide

Call

os.Exit

log.Fatal*

only in
main()
. All other functions should return errors to signal failure.

Why this matters:

Non-obvious control flow: Any function can exit the program
Difficult to test: Functions that exit also exit the test
Skipped cleanup:
```
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
}

Exit Once

Prefer to call

os.Exit

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:

Short
```
main()
```
function with single exit point
All business logic is testable
```
defer
```
statements always execute

Quick Reference

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-packages

NPX Install

Tags

SKILL.md Content

Go Packages and Imports

Package Organization

Avoid Util Packages

Package Size

Imports

Import Organization

Import Grouping (Extended)

Import Renaming

Blank Imports (
`import _`
)

Dot Imports (
`import .`
)

Avoid init()

Exit in Main

Exit Once

Quick Reference

See Also

go-packages

NPX Install

Tags

SKILL.md Content

Go Packages and Imports

Package Organization

Avoid Util Packages

Package Size

Imports

Import Organization

Import Grouping (Extended)

Import Renaming

Blank Imports (import _)

Dot Imports (import .)

Avoid init()

Exit in Main

Exit Once

Quick Reference

See Also

Blank Imports (
`import _`
)

Dot Imports (
`import .`
)