Naming packages

In this lesson we cover practical, idiomatic guidelines for naming Go packages. Clear package names reduce cognitive overhead when reading imports and call sites, and they help your codebase remain discoverable and maintainable. Key concepts covered:

Choosing descriptive package names
Avoiding redundant identifiers
Aligning package clauses and directory names
Export rules for identifiers

1. Prefer descriptive package names

Choose package names that describe the responsibility or behavior the package provides. Avoid generic names like util, helpers, or common because they hide intent and make it harder to find functionality. Prefer small, focused packages whose names make their purpose obvious. For example, instead of one generic util package containing unrelated helpers for name extraction and string formatting, split them into two purpose-driven packages:

// In directory extract
package extract

// Names extracts all names from input and returns them as a slice.
func Names(s string) []string {
    // implementation...
}

// In directory format
package format

// Names formats the input string in a particular way and returns the result.
func Names(s string) string {
    // implementation...
}

When imported and used, the package name disambiguates the meaning:

import (
    "example.com/project/extract"
    "example.com/project/format"
)

names := extract.Names("Alice, Bob, Charlie")
out := format.Names("alice")

This reads naturally as extract.Names and format.Names, which is clearer than util.ExtractNames or util.FormatString.

Use focused, descriptive package names. The package name plus the identifier should read naturally at the call site (for example, extract.Names or format.Names).

2. Avoid repeating the package name inside identifiers

Do not repeat the package name inside exported identifiers. The package name already provides context at the call site, so including it in function names makes names redundant and verbose. Prefer:

extract.Names (not extract.ExtractNames)
format.Names (not format.FormatString)

Also remember that exported identifiers in Go are capitalized. If you want a function to be usable from other packages, start it with an uppercase letter (e.g., Names).

Avoid redundant naming like extract.ExtractNames. Repetition makes APIs noisy and harder to use.

3. Package clause and directory name conventions

Files in a single directory should normally use the same package clause. For discoverability and consistency:

Make the package name match the directory name.
Keep all non-test files in the directory using the same package clause.

Common, intentional exceptions:

package main — used for executables; packages named main are not importable.
Test packages — tests may use package foo_test to test the package from the external perspective.

Aside from these, prefer a one-to-one mapping of directory ↔ package name to reduce confusion when importing.

Quick reference table

Guideline	Rationale	Example
Use short, descriptive names	Improves readability at call sites	`extract`, `format`
Don’t repeat the package name in identifiers	Package qualifier already provides context	`extract.Names` (not `extract.ExtractNames`)
Export only what’s necessary	Keep API surface minimal and intentional	`func Names(...)` for exported, `func names(...)` for unexported
Match package clause to directory	Easier discovery and consistent imports	Directory `extract/` → `package extract`

Summary

Choose short, descriptive package names that clearly convey responsibility.
Let package names disambiguate identifiers — avoid repeating the package name inside function names.
Export names by starting them with an initial capital letter only when they must be visible outside the package.
Keep the package clause consistent across files in a directory and match it to the directory name, except for valid exceptions like main and _test packages.

Introduction

Introduction: Modules, Packages, and Imports

Core packages

API Development Project

CI/CD pipeline

Concurrency

1. Prefer descriptive package names

2. Avoid repeating the package name inside identifiers

3. Package clause and directory name conventions

Quick reference table

Summary

Links and references

Watch Video

Practice Lab

​1. Prefer descriptive package names

​2. Avoid repeating the package name inside identifiers

​3. Package clause and directory name conventions

​Quick reference table

​Summary

​Links and references

Watch Video

Practice Lab

1. Prefer descriptive package names

2. Avoid repeating the package name inside identifiers

3. Package clause and directory name conventions

Quick reference table

Summary

Links and references