Idiomatic Code Organization

Go Project Structure

Organize your Go projects using the following structure for clarity and maintainability:

• Place the main entry point in a cmd/ directory;
• Store application code in an internal/ directory for private packages;
• Keep reusable packages in a pkg/ directory;
• Group configuration files and assets in a configs/ or assets/ directory;
• Place third-party dependencies in a vendor/ directory if vendoring is required.

A typical layout:

myapp/
├── cmd/
│   └── myapp/
│       └── main.go
├── internal/
│   └── service/
│       └── service.go
├── pkg/
│   └── utils/
│       └── utils.go
├── configs/
├── assets/
├── go.mod
└── go.sum

File Organization and Naming

• Use one package per directory; name the directory after the package;
• Name files to reflect their purpose, such as http.go, db.go, or service.go;
• Keep related types and functions together for discoverability;
• Avoid stutter by matching package and type names (e.g., user.User is redundant, prefer user.Model).

Package Design Principles

• Keep packages focused on a single responsibility;
• Expose only what is necessary: use lowercase for unexported identifiers and uppercase for exported ones;
• Avoid circular dependencies between packages;
• Document packages and exported functions using Go doc comments.

Best Practices for Clean Code

• Write short, focused functions;
• Use clear, descriptive names for variables and functions;
• Prefer composition over inheritance;
• Handle errors explicitly and consistently;
• Write tests alongside your code in *_test.go files.

Following these conventions makes your Go projects easier to understand, test, and maintain as they grow.