Project layout
cmd/ entrypoints
The cmd folder holds one subfolder per runnable program, and each subfolder owns a small main package. Logic stays in libraries, while main only wires flags, input, and output together.
The tree below shows a module named myapp with one tool, one library, and the files every Go project needs at the root. The main file imports the library by its full module path.
myapp/cmd/wordfreq/main.go
myapp/internal/count/count.go
myapp/go.mod
myapp/README.md
package main
import (
"fmt"
"myapp/internal/count"
)
func main() {
fmt.Println(count.Words("go is fast"))
}
3
internal/ packages
The internal folder marks code as private to its parent module. The compiler rejects imports of internal packages from outside, so helpers can change freely without breaking strangers.
Put project specific logic into internal first. Only code that other modules should reuse earns a public home, and that promotion stays a deliberate choice rather than an accident.
package count
import (
"strings"
)
func Words(s string) int {
return len(strings.Fields(s))
}
When pkg helps
The pkg folder hosts libraries that other modules may import one day. Classic residents include reusable clients, parsers, and small algorithm packages with no project specific assumptions.
Most small projects never need pkg. Starting with internal keeps every option open: moving a mature package from internal to pkg later is a simple rename once outside users appear.
README and docs
A README answers four questions in order: what the project does, how to install it, how to run it, and how to test it. Short files that answer these questions get read, while long essays get skipped.
Go doc comments back the README up. A one sentence comment on every exported name feeds the go doc tool, so the terminal always shows fresh reference text next to the code.
# myapp
Counts words from files or stdin.
## Install
go install myapp/cmd/wordfreq@latest
go doc ./internal/count
package count
func Words(s string) int
Next: Capstone: wordfreq CLI
Article author: Arthur Isaev