A package groups related Go declarations and gives other code a boundary to depend on. A directory can contain other package directories, but that does not create subpackages: code in net/http has no inherited access to net and can use only its exported elements. section 2.12.2
/net
/http
client.go
...
/smtp
auth.go
...
addrselect.go
...
The net layout places related packages near one another without making http or smtp children of the net package. section 2.12.2
When a package layout becomes hard to follow, check the boundaries:
- Avoid splitting code prematurely into dozens of one- or two-file packages; also avoid packages so large that their names lose meaning. A small package is reasonable when its code is cohesive and belongs nowhere else. section 2.12.2 section 2.13
- Name a package for what it provides, using a short, expressive, conventionally lowercase word. Minimize what it exports. section 2.12.2
- Choose grouping by application context or technical layer according to the use case, then stay consistent; do not force a final structure before the code’s relationships are clear. section 2.12.2
Replace a catch-all package with an expressive API
A caller using util.NewStringSet and util.SortStringSet learns little from the package name, while the function names repeat their subject. With a cohesive stringset package, the calls become stringset.New and stringset.Sort. A Set type can move the second operation to set.Sort(). This is a reason to replace a vague catch-all package, not a ban on every small or utility package. section 2.13 section 11.7
Package boundaries also shape tests. Files in one folder normally share a package, but a test file may use a _test package. A counter_test test must import counter and cannot reach its unexported count variable, so it tests the exported Inc behavior instead. Use that separation when a test should survive changes to implementation details. section 11.9.2
Dependencies matter at startup too: a package’s declarations are evaluated and its init functions run when it is initialized. If main depends on redis, redis initializes first. Do not make behavior depend on init ordering across files within one package; renaming files can change that order. section 2.3.1
