AdGuardHome/HACKING.md

AdGuardHome Developer Guidelines

As of 2020-11-12, this document is still a work-in-progress. Some of the rules aren't enforced, and others might change. Still, this is a good place to find out about how we want our code to look like.

Git

• Follow the commit message header format:

  pkg: fix the network error logging issue
  

  Where pkg is the package where most changes took place. If there are several such packages, just write all.

• Keep your commit messages to be no wider than eighty (80) columns.

• Only use lowercase letters in your commit message headers.

Go

• https://github.com/golang/go/wiki/CodeReviewComments.

• https://github.com/golang/go/wiki/TestComments.

• https://go-proverbs.github.io/

• Avoid init and use explicit initialization functions instead.

• Avoid new, especially with structs.

• Document everything, including unexported top-level identifiers, to build a habit of writing documentation.

• Don't use underscores in file and package names, unless they're build tags or for tests. This is to prevent accidental build errors with weird tags.

• Don't write code with more than four (4) levels of indentation. Just like Linus said, plus an additional level for an occasional error check or struct initialization.

• Eschew external dependencies, including transitive, unless absolutely necessary.

• No goto.

• No shadowing, since it can often lead to subtle bugs, especially with errors.

• Prefer constants to variables where possible. Reduce global variables. Use constant errors instead of errors.New.

• Put comments above the documented entity, not to the side, to improve readability.

• Use gofumpt --extra -s.

  TODO(a.garipov): Add to the linters.

• Use linters.

• Use named returns to improve readability of function signatures.

• When a method implements an interface, start the doc comment with the standard template:

  // Foo implements the Fooer interface for *foo.
  func (f *foo) Foo() {
      // …
  }
  

• Write logs and error messages in lowercase only to make it easier to grep logs and error messages without using the -i flag.

• Write slices of struct like this:

  ts := []T{{
          Field: Value0,
          // …
  }, {
          Field: Value1,
          // …
  }, {
          Field: Value2,
          // …
  }}
  

Text, Including Comments

• Text should wrap at eighty (80) columns to be more readable, to use a common standard, and to allow editing or diffing side-by-side without wrapping.

  The only exception are long hyperlinks.

• Use U.S. English, as it is the most widely used variety of English in the code right now as well as generally.

• Use double spacing between sentences to make sentence borders more clear.

• Use the serial comma (a.k.a. Oxford comma) to improve comprehension, decrease ambiguity, and use a common standard.

• Write todos like this:

  // TODO(usr1): Fix the frobulation issue.
  

  Or, if several people need to look at the code:

  // TODO(usr1, usr2): Fix the frobulation issue.
  

Markdown

• TODO(a.garipov): Define our Markdown conventions.

YAML

• TODO(a.garipov): Find a YAML formatter or write our own.

• All strings, including keys, must be quoted. Reason: the NO-rway Law.

• Indent with two (2) spaces.

• No extra indentation in multiline arrays:

  'values':
  - 'value-1'
  - 'value-2'
  - 'value-3'
  

• Prefer single quotes for string to prevent accidental escaping, unless escaping is required.