Hello, I’m fried fish.

One of the things that sparked a lot of discussion in the Go community a while back was the golang-standards/ project-Layout “Standard Layout for Go” debate.

Unexpectedly, the May Day holiday, a serious look, this issues has been put forward nearly a month, still in the hot discussion stage, I think, we need to have a good chat about this topic.

Fry fish to take you to understand the cause and effect, and then share my opinion and business reality.

background

Where the problem occurred

There is a project on making Spaghetti (github.com/adonovan/spaghetti), is one of the Go package dependency analysis tool.

The directory structure of the project is as follows:

It doesn’t look complicated, the amount of code is not much, the file tiling is not more than one screen, it is a relatively simple layout of the project.

One of the guys came up with a PR that explicitly expected the project to follow the “standard” layout given by golang-standards/ project-Layout. :

I guess the project may be because the Go, HTML, JS, PNG and go.mod files are placed together, causing the student a little tangle, feel a bit messy?

What does a standard layout look like

In the Golang-standards/project-Layout project, it claims to:

The organization name of the project is also “Golang-standards”, which provides a basic Go project layout, shown in a condensed form as follows:

Project-layout ├─ API ├─ CMD ├─ Configs ├─ docs ├─ Go. Mod ├─ Internal ├─ Scripts ├─ Vendor ├─ .Copy the code

  • / CMD: The project’s main application.

  • /internal: Private application code libraries that do not want to be imported by others.

  • The actual application code can be placed in the /internal/app directory (e.g., internal/app/myapp).

  • The application’s shared code is placed in the /internal/ PKG directory (e.g., internal/ PKG /myprivlib).

  • / PKG: library code that external applications can use (e.g. / PKG/myPubliclib). Other projects will import these libraries to keep the project running.

  • /vendor: Application dependencies, which can be obtained by executing go Mod vendor.

  • /configs: configs file template or default configuration.

  • Init: System initialization (Systemd, upstart, SYSV) and process management (runit, supervisord) configuration.

  • /scripts: : Scripts used to perform various build, install, analyze, etc.

For a more detailed layout introduction, see the README of the project-Layout project, which basically takes all aspects of the catalog into account (many hands make light work).

Because the content is too long, so I won’t show it all.

Why Russ Cox showed up

Coincidentally, the author of the project is a former Google employee who wrote the Gopl. IO project (5.1K Stars).

Only 23 minutes later, Russ Cox (@RSC), the GoTeam Leader, appeared and expressed his opposition with a new issue:

Golang-standards/project-Layout README makes it clear that this is not an official standard and states as follows:

it is a set of common historical and emerging project layout patterns in the Go ecosystem.

Russ Cox was critical of the “inaccuracy” of the claim that “this is a set of historical and emerging project layout patterns that are common in the Go ecosystem.”

For example, most packages in the Go ecosystem do not place importable packages in PKG subdirectories. More broadly, what is described here is very complex engineering projects, whereas Go warehouses tend to be much simpler.

In addition, unfortunately, this project layout is called “Golang-standards” (Golang standards) in the name of the organization, which is not really official and misleading.

Russ Cox objected to the reasons

After understanding the “standard” project layout provided by the project-layout project and the background of issues raised by Russ Cox.

We learn more about Russ Cox’s fundamental concern that this is not true. There are two problems with project-layout:

  • It claims to be the sponsor of Go standards, but it is not, because they are not official Go standards.

  • Its proposed project layout standards are too complex to be a reasonable standard.

What are the criteria for the Go project layout

After this issue was raised, a lot of people asked Russ Cox, what is the layout standard of Go project?

The official response from Russ Cox is that the minimum standard layout for an importable Go repo is:

  • Place a LICENSE file in your root directory.

  • Place a go.mod file in your root directory.

  • Put the Go code in the REPO, in the root directory, or as a directory tree as you see fit.

That’s it. That’s the standard. It’s not that complicated. You do not need a layout like a project-layout project. Go’s official Golang.org/x repository breaks every one of these “rules” of Project-Layout.

Go proposal

After a long war of words, a proposal has been put forward in the official Go warehouse to release the relevant proposal:

Guesses may have the following possibilities:

  • GitHub project Golang-Standards/Proje-Layout is willing to change its name and not call itself “Golang-Standards”, but it’s unlikely because it’s already been suggested, but the author doesn’t say anything.

  • Go officially provides instructions for the Go standard project layout.

  • Go official does not do constraints, only do statements, may output articles.

As we continue to pay attention to the proposal, we can know the development, portal: Issues #45861.

As a rule, I guess the third option is the most likely, because it’s hard to come up with a standard that all developers agree on, and the preferences of each division and team may vary.

conclusion

In fact, anything that calls itself the “XX standard” can cause problems when it becomes famous. Like the Golang-standards/project-Layout project mentioned in this article.

For example, if you are the Leader of a project, one day when your colleague is presented with the “standard” to suggest modification, will it be wonderful to say that this is the “standard” of the project?

Similarly, I have a friend whose company had only one DDD standard in its early years and wanted to unify it. As a result, each of the business students involved in DDD thought that the predecessors were not standard, and everyone created their own DDD standards.

There will always be those who want to define absolute “standards” or “best practices”. It’s hard to define, but the best thing is to be able to form a basic consensus within a team, which involves more than just technology…

What do you think of this? Please leave a comment in the comments section and communicate with us!

If you have any questions, welcome feedback and communication in the comments section. The best relationship is mutual achievement. Your praise is the biggest motivation for the creation of fried fish, thank you for your support.

The article is constantly updated, you can search “brain into fried fish” on wechat to read; In this paper, making github.com/eddycjy/blo… Star has been included, welcome to urge more.