diff --git a/project_structure.md b/project_structure.md index f268b8b..d1642e2 100644 --- a/project_structure.md +++ b/project_structure.md @@ -14,7 +14,7 @@ On the complex end of the spectrum, projects like [CockroachDB](https://github.c | [gitea](https://github.com/go-gitea/gitea) | 223,761 | 39,001 | | [hugo](https://github.com/gohugoio/hugo) | 148,613 | 16,642 | | [go-github](https://github.com/google/go-github) | 117,131 | 15,637 | -|[traefik](https://github.com/traefik/traefik) | 107,542 | 9,154 | +| [traefik](https://github.com/traefik/traefik) | 107,542 | 9,154 | | [gio](https://gioui.org/) | 47,283 | 5,122 | | [gorilla/mux](https://github.com/gorilla/mux) | 6,661 | 763 | @@ -23,20 +23,25 @@ The complexity scores are rough estimates, but are useful in realizing how compl If your project is simple, do not add unnecessary structure. This increases the cognitive load of anyone trying to use the project. ### Organize Code by Responsibility - +When creating modules and packages, be sure to define what the package's responsibility is. This is encouraged by the standard go practice of having a [package comment](https://blog.golang.org/godoc). Difficulty in defining a responsibility/purpose is a sign of an unnecessary or too broad package. ### Package `internal` +`internal` is additional complexity, and should really only be used for packages with substantial users. If there are only a few people using the project and it is in development, it may not be necessary to use this. + +[Use internal packages to reduce your public API surface](https://dave.cheney.net/2019/10/06/use-internal-packages-to-reduce-your-public-api-surface) ### Package `pkg` +`pkg` should not be used in the package path. It is redudant at best (a package path always leads to a package). + +[rakyll.org](https://rakyll.org/style-packages/) + +[Organzing Go Code](https://talks.golang.org/2014/organizeio.slide#6) + +[What's in a Name?](https://talks.golang.org/2014/names.slide#15) + ### Use Encapsulation Tools to Create Project Structure +Modules, packages, files, funcs, and structs are all encapsulation tools. Use them according to their purpose. Using a package for one exported func (and none unexported) is probably a misuse. -Just as structs, funcs, files, packages, and modules are - -### Adding Complexity Should be Justified - -### Use Other Methods of Abstraction - -### Other Resources - -https://rakyll.org/style-packages/ \ No newline at end of file +### Adding Complexity Should Have a Rationale +Adding packages adds complexity to your project. The onus is on the person adding the complexity to rationalize it. If there is no rationale, it should probably be removed.