Style guidelines

Style basis

The core of the styling conventions used in this repository are based off of practices used on the Go standard libary. Some essential documents one should read before writing Go would be:

• Effective Go
• Code Review Comments, which describes commonly encountered comments in order to avoid them.

Please feel free to flag (by means of an issue) any inconsistency, problem, or missing entry that you notice.

General guidelines

• Get inspired from other source code files.
• Don't forget the copyright header.
• Stay compact. Avoid creating paragraphs by introducing empty lines as much as possible, especially around curly braces. The curly brace already creates enough spacing for a reader. Exceptions can be made in long functions where there is a big shift in purpose.
• Split imports into 3 groups, separated by an empty line:
  • Standard library
  • This repository
  • External packages
• When leaving TODOs, use the notation TODO(name) where name is the Github username of the person that should attend to this task. If the task is good enough for anyone, use TODO(x).
• If your test addresses hot paths or performance improvements, post the results of before and after as the output of the benchcmp tool in the PR or commit description.
• When the PR is on Github, it is a very good practice to review your own code yourself, from a reviewer's point of view. You are bound to see things you didn't in your editor! Look at it through the eyes of a stranger and make sure it is easy to understand and where it's not, make an extra effort to make it so by either simplifying (if possible) or adding more clarity through comments.
• Always document complex structures, regardless of whether they are exported, unexported or test code!
• Keep the happy path to the left!

Naming things

In general, identifier names in Go should be as succinct as possible (but not cryptic) and follow the principle "The greater the distance between a name's declaration and its uses, the longer the name should be". The "What's in a name" talk by Andrew Gerrand gives a very good description of the naming principles followed.

• If a variable is commonly named one way, use that name regardless of context, whenever possible. Some examples:
  • i is always the loop iterator
  • r is many times an io.Reader
  • buf or b is a common name for a buffer
  • ...
• Focus on readability over brevity. This means that the code must make the algorithm behind it easy to read, as opposed to reading out nicely in English. See slide#7 vs slide#8.

Tests

• Test names must generally be one word. In Go, the test name is more of an identifier, as opposed to a description of the test like in other languages. If one word is not possible, it's fine to use two, but use a dash (-) to separate instead of space.
• Use sub-tests instead of standalone tests, whenever grouping makes sense.
• Factor out shared code to the top-level test and avoid repetition in multiple tests.

Comments

• Feel free to use inline comments wherever the code doesn't speak on its own. Use the // notation followed by a space.
• Inline comments describing if statements should be placed inside the if statement on the first line.
• Try to use correct grammar in the documentation and end sentences with a period.
• Feel free to add URLs into comments, pointing to manuals, documentation, Github issues, PRs, or anything necessary to give the context.
• Don't go overboard on wording, find the right balance between clarity and prose.