Best Practices for Naming Directories, Packages, and Files in Go Projects

In programming, choosing the right naming conventions is essential for readable and maintainable code. For large Go projects, file naming is a key part of a clear project structure, improving development efficiency and reducing communication overhead.

Before discussing file naming, we review Go directory and package naming conventions.

Directory Names

Common consensus for Go directory names:

All lowercase words, e.g., cmd , internal .

Use hyphens when necessary, e.g., kube-scheduler , kube-controller-manager .

Projects themselves follow the same rules. The Kubernetes project, for example, uses all‑lowercase directories and hyphens where appropriate.

Examples of good directory names:

cmd
internal
pkg
task
kube-scheduler
kube-controller-manager

Examples of bad directory names:

CMD
kubeScheduler
KubeScheduler
kube_scheduler

Special cases such as third_party (using an underscore) are accepted by convention.

Additional project‑name guidelines include using functional descriptions (e.g., userapi , redis-go ) or code‑names (e.g., kratos , kubernetes ), and avoiding name collisions by adding prefixes or suffixes when needed.

Package Names

The Go team provides authoritative guidance for package names:

Short, descriptive, lower‑case single words (e.g., bufio rather than buf or buffer ).

Avoid underscores or mixed‑case; use simple nouns like time , list , http .

Use abbreviations wisely (e.g., strconv , syscall , fmt ).

Do not steal common names from user code; avoid generic names like common , util , shared , lib .

Package and directory names should match; avoid plural forms unless they are part of the official import path.

Testing packages end with _test , hidden files start with . or _ , and OS/ARCH‑specific files use suffixes like _linux.go or _amd64.go .

Good package name examples:

controller
stringset
tabwriter

Bad examples:

MyUtil
util
time // collides with std lib
tabWriter
TabWriter
tab_writer

File Names

There is no official Go standard for file names, but community consensus suggests:

All lower‑case words, e.g., mksizeclasses.go .

Use underscores (snake_case) when necessary, e.g., abi_string.go .

Exceptions include test files ending with _test.go , hidden files starting with . or _ , and OS/ARCH‑specific suffixes.

Some developers prefer not to use underscores for two‑word names (e.g., taskstatus.go ) and only use them for longer names (e.g., import_known_versions.go ).

Good file name examples:

router.go
middleware.go
webshell.go

Bad file name examples:

routers.go // plural
fooBar.go
Service.go

Summary

Naming is one of the two hard problems in computer science. For Go projects, the community recommends using lower‑case names, kebab‑case for directories when needed, and snake_case for files, while allowing exceptions for special cases.

Key takeaways:

Prefer lower‑case over camelCase or PascalCase.

Use kebab‑case for directories and snake_case for files when necessary.

Recognize the gray area where the choice between kebab‑case and snake_case is ambiguous.

For further reading, see the Go Blog, Effective Go, and various community resources linked below.