Our AI writing assistant, WriteUp, can assist you in easily writing any text. Click here to experience its capabilities.

The one-and-only, must-have, eternal Go project layout

View Original View Raw

Summary

This article is about how to lay out a Go project in the best way. It explains different project types and how they should be laid out, provides best practices, and offers examples of what a layout might look like. It also discusses the pros and cons of using a "pkg" directory and advises that it should be used with caution.

Q&As

What is the Go proverb regarding the layout of a Go project?
The Go proverb regarding the layout of a Go project is "Design the architecture, name the components, document the details."

What are the benefits of using a "pkg" directory in a Go project?
The benefits of using a "pkg" directory in a Go project are a cleaner repository, no naming collision with non-Go assets, and a clear sign for project users that the directory contains public packages.

Should pure library projects use a "pkg" directory?
Pure library projects should not use a "pkg" directory.

What are the consequences of using a "pkg" directory in a large application project?
The consequences of using a "pkg" directory in a large application project are that the packages will be open for everyone to use, the project owner will receive issues and pull requests for those packages that are not related to the parent project, and the packages might start to live their own life.

What is the advice for dual application/library projects?
The advice for dual application/library projects is to keep public library packages separate from the application project and to put packages that serve the application but do not work well as stand-alone packages into the internal directory.

AI Comments

👍 This article does an excellent job of breaking down the complexities of laying out a Go project. It provides examples and best practices for different types of projects that make it easier to understand.

👎 This article is overly long and could have been condensed into a more concise format. It also does not provide enough detail or examples in some areas.

AI Discussion

Me: It's about the implications of the Go project layout. The article argues that there is no one-size-fits-all project layout and that the optimal layout depends on the use case. It also provides some best practices for organizing Go projects, like naming packages by their functionality, avoiding grab-bag package names, and using special directory names like internal/, testdata/, and vendor/.

Friend: Interesting. So what are the implications of this article?

Me: Well, it implies that you should use best practices when organizing your Go project, but also take into account the specifics of your project when deciding on the layout. For example, CLI tools don't require much structure, and library projects should have the library code at the root and command-line tools in a cmd directory. For larger projects with lots of non-Go assets, it might make sense to use a pkg directory, but this comes with consequences like having to increase the minor version of the whole project if a feature is added to one of the public packages. In such cases, it might be better to split the dual application/library project into two separate projects.

Action items

Research the Go proverbs and create a list of best practices for laying out a Go project.
Create a project template that follows the best practices for laying out a Go project.
Experiment with different project layouts to determine which one works best for your specific use case.

Technical terms

Go project layout: The structure of a project written in the Go programming language.
Go proverbs: A list of sayings presented by Rob Pike at a talk at Gopherfest 2015.
Go module: A module is a collection of related Go packages that are released together.
Semantic versioning: A versioning system that uses a three-part version number (major.minor.patch) to indicate the level of changes in a release.
Go proxy server: A server that provides a consistent way to download and install Go packages.
GOPATH: The environment variable that specifies the location of the workspace directory.
Framework: A set of tools and libraries that provide a structure for developing software applications.
Standard Go Project Layout: A project template that provides a structure for large application projects.