Go Standards Project Layout

There are only two hard things in Computer Science: cache invalidation and naming things.

-- Phil Karlton

For new Go programmers a third hardest thing might be package layout. The truth is, it doesn't have to be hard at all.

Alright, here is the secret to the hard party: forget everything you know from other languages, unless that other language is C.

Strangely, this might be the most controversial issue in the Go community, including advice so bad that project contributors had to file a bug: https://github.com/golang-standards/project-layout/issues/117

Honestly, https://medium.com/@benbjohnson/standard-package-layout-7cdbc8391fc1#.ds38va3pp is probably the best advice, but don't feel that you need to follow all of it immediately. You probably won't have mocks at first. You probably don't need to decouple things at first. Remember, loose coupling is only a good thing if you need it. Otherwise you are paying a cost. Simplicity is far more valuable than future flexibility especially when YAGNI.

There is a list of some great TODO and DO NOT items here:
https://rakyll.org/style-packages/

Along with common and util, I believe api is a package name which should be avoided. It should be obvious why: all packages have an API. api certainly is a short name, but there is nothing clear about it. https://blog.golang.org/package-names Package names should be short and clear. If you want to name a package api, instead, ask yourself, api for what? and name the package the answer to that question.

Strangely, there is a ton of official guidance on that page which is completely ignored by other recommendations. I'll link it again: https://blog.golang.org/package-names

When you read someone else's advice, such as: https://peter.bourgon.org/go-best-practices-2016/#repository-structure consider each point against the official advice of https://blog.golang.org/package-names and if it doesn't fit, discard it. Also consider each point against YAGNI.

If you read enough of these advice posts you'll being to notice some are not prescriptive. That is great. Prescriptive advice is harmful. No one can know your specific needs and circumstances. Following the wrong advice can be very expensive in the long run. Instead look at advice like https://www.ardanlabs.com/blog/2017/02/design-philosophy-on-packaging.html Notice how it is about philosophy and usability. It is not about how the programmer writing the code feels or wants things to be.

At any step, ask yourself, has this practice added value? If it hasn't, then don't do it. Undo it even. Value is also subjective. While I don't find a pkg dir to have any value, another team might find it to be very valuable to put everything there, away from the non-Go code things (docs, scripts, etc) in their repo. That is fine. Recognize that there is no right on wrong here, there is only our different values.

My favorite line of advice is from: https://christine.website/blog/within-go-repo-layout-2020-09-07 which reasons about the advice to say: "...Leaves the development team a lot more agency to decide how to name things" Take your agency. Ignore prescription.

All that said, how would I divide MVC into packages I wouldn't... until I need to.