Skip to content

Coding conventions

There are a few things to note when coding in flamingo, so please try to follow these guidelines.

Generals

  • 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 opentelemetry/tags package for tracing/stats tags.

Public interfaces and methods

Limit the public surface to the bare minimum.

Dingo

Use dingo-compatible Inject(...) methods rather than inject:"" tags on public members.

Testing

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. For example:

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 _test to the package name in your test files.
  • Use example_test.go with Example* test functions where it is useful to show examples.
  • Add a doc.go in case you want to provide a documentation for the package, and it doesn't fit anywhere else.

Documentation

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 ## Subheadline in order to show up in the generated table of content later.

Releases

Flamingo follows Semantic Versioning. Minor versions are created any now and then.

Code Generation

We encourage the use of code generation, however it is necessary to stick to some rules:

  • Always use go:generate to make sure the generation is reproducible by anyone.
  • Always use go run toolname instead of toolname to make sure the tool's version is recorded in go.mod.

Example: use

//go:generate go run go run github.com/vektra/mockery/v2@v2.22.1

instead of

//go:generate mockery