> ## Documentation Index
> Fetch the complete documentation index at: https://notes.kodekloud.com/llms.txt
> Use this file to discover all available pages before exploring further.
# Naming packages
> Guidelines for choosing clear, concise Go package names, avoiding redundancy, aligning package clauses with directories, and controlling exported identifiers for readable, maintainable code.
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:
```go theme={null}
// In directory extract
package extract
// Names extracts all names from input and returns them as a slice.
func Names(s string) []string {
// implementation...
}
```
```go theme={null}
// 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:
```go theme={null}
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.
## Links and references
* [Effective Go — Packages](https://go.dev/doc/effective_go#package-names)
* [The Go Programming Language Specification — Packages](https://go.dev/ref/spec#Packages)
* [Go Blog: How to Write Go Code](https://go.dev/blog/code)
This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.