From d5538bbe3a4eb574860e8a69a8f5c13f3541f623 Mon Sep 17 00:00:00 2001 From: jeff Date: Sat, 17 Jul 2021 05:51:38 +0000 Subject: [PATCH] Update 'project_structure.md' --- project_structure.md | 27 ++++++++++++++++----------- 1 file changed, 16 insertions(+), 11 deletions(-) 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.