Go Project Layout: The Controversy
Was researching Go project layouts. Found an interesting debate about golang-standards/project-layout.
The Repository
golang-standards/project-layout is a popular repo showing a “standard” Go project structure with /cmd, /pkg, /internal, etc.
Problem: It’s not actually a standard. Just one person’s opinion.
The Debate
Issue #117 discusses concerns:
- Misleading name (not endorsed by Go team)
- Overly complex for most projects
- Cargo-cult adoption without understanding
Many developers copy this structure blindly, thinking it’s official.
What Go Actually Recommends
From the Go team: Keep it simple.
Eli Bendersky’s simple Go project layout:
1
2
3
4
5
myproject/
main.go # or cmd/myapp/main.go if multiple binaries
handler.go
handler_test.go
go.mod
That’s it. Add directories as you need them.
When to Add Structure
Small project:
1
2
3
4
myproject/
main.go
user.go
post.go
Multiple binaries:
1
2
3
4
5
6
7
myproject/
cmd/
server/main.go
worker/main.go
internal/
user.go
post.go
Large project: Add /internal, /pkg, /api as needed. But start simple.
Lesson
Don’t cargo-cult project structures. Start minimal, add complexity only when necessary.
The “standard” layout works for large teams and complex projects. For most projects, it’s overkill.