There are a few things to note when coding in flamingo, so please try to follow these guidelines.
- go fmt applies
- appropriate godoc comments
- go vet applies
- Effective Go applies
- Always handle errors
- Always verify type assertions with the second
_, ok := v.(T)bool flag.
Usage of context.Context¶
The Context is always the first argument to a method/function. Do not check, and do not pass, nil contexts, as they are forbidden! Do not use the context for general passing of scoped data, unless it's explicit necessary.
Use the opencensus/tags package for tracing/stats tags.
Public interfaces and methods¶
Limit the public surface to the bare minimum.
Inject(...) methods rather than
on public members.
Every public exposed Method/Function/Type should have unittests. Trivial Tests (like testing Getter/Setter) are not necessary. If possible please provide examples as well.
Testing and documenting Code¶
In go you place your tests directly in the package. You can simply use the standard go testing tool.
To run tests of a certain package simply run the
go test tool.
go test -v flamingo.me/flamingo/v3/framework/config
Also, we want to provide a useful
go doc api documentation. Therefore, stick to the go doc conventions.
Read more here: blog.golang.org/godoc-documenting-go-code
- Prefer to do "blackbox" tests and append
_testto the package name in your test files.
Example*test functions where it is useful to show examples.
- Add a
doc.goin case you want to provide a documentation for the package, and it doesn't fit anywhere else.
Each module should have a Readme.md file in its root:
- The first line should be a h1 headline with the Title of the module e.g.
# Cart Module
- This will show up in the rendered documentation as page title as well
- Any other headline should at least be h2
## Subheadlinein order to show up in the generated table of content later.
Flamingo follows Semantic Versioning. Minor versions are created any now and then.
We encourage the use of code generation, however it is necessary to stick to some rules:
- Always use
go:generateto make sure the generation is reproducible by anyone.
- Always use
go run toolnameinstead of
toolnameto make sure the tool's version is recorded in go.mod.
//go:generate go run github.com/vektra/mockery/cmd/mockery