AdGuardHome/HACKING.md

AdGuard Home Developer Guidelines

Following this document is obligatory for all new code. Some of the rules aren't enforced as thoroughly or remain broken in old code, but this is still the place to find out about what we want our code to look like and how to improve it.

The rules are mostly sorted in the alphabetical order.

Contents

• Git
• Go
  • Code
  • Commenting
  • Formatting
  • Naming
  • Testing
  • Recommended Reading
• Markdown
• Shell Scripting
  • Shell Conditionals
• Text, Including Comments
• YAML

Git

• Call your branches either NNNN-fix-foo (where NNNN is the ID of the GitHub issue you worked on in this branch) or just fix-foo if there was no GitHub issue.

• Follow the commit message header format:

  pkg: fix the network error logging issue
  

  Where pkg is the directory or Go package (without the internal/ part) where most changes took place. If there are several such packages, or the change is top-level only, write all.

• Keep your commit messages, including headers, to eighty (80) columns.

• Only use lowercase letters in your commit message headers. The rest of the message should follow the plain text conventions below.

  The only exceptions are direct mentions of identifiers from the source code and filenames like HACKING.md.

Go

Not Golang, not GO, not GOLANG, not GoLang. It is Go in natural language, golang for others.

— @rakyll

Code

• Always recover from panics in new goroutines. Preferably in the very first statement. If all you want there is a log message, use log.OnPanic.

• Avoid fallthrough. It makes it harder to rearrange cases, to reason about the code, and also to switch the code to a handler approach, if that becomes necessary later.

• Avoid goto.

• Avoid init and use explicit initialization functions instead.

• Avoid new, especially with structs, unless a temporary value is needed, for example when checking the type of an error using errors.As.

• Check against empty strings like this:

  if s == "" {
          // …
  }
  

  Except when the check is done to then use the first character:

  if len(s) > 0 {
          c := s[0]
  }
  

• Constructors should validate their arguments and return meaningful errors. As a corollary, avoid lazy initialization.

• Prefer to define methods on pointer receievers, unless the type is small or a non-pointer receiever is required, for example MarshalFoo methods (see staticcheck-911).

• Don't mix horizontal and vertical placement of arguments in function and method calls. That is, either this:

  err := f(a, b, c)
  

  Or, when the arguments are too long, this:

  err := functionWithALongName(
          firstArgumentWithALongName,
          secondArgumentWithALongName,
          thirdArgumentWithALongName,
  )
  

  Or, with a struct literal:

  err := functionWithALongName(arg, structType{
          field1: val1,
          field2: val2,
  })
  

  But never this:

  err := functionWithALongName(firstArgumentWithALongName,
          secondArgumentWithALongName,
          thirdArgumentWithALongName,
  )
  

• Don't rely only on file names for build tags to work. Always add build tags as well.

• Don't use fmt.Sprintf where a more structured approach to string conversion could be used. For example, aghnet.JoinHostPort, net.JoinHostPort or url.(*URL).String.

• Don't use naked returns.

• Don't write non-test 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.

  The exception proving the rule is the table-driven test code, where an additional level of indentation is allowed.

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

• Minimize scope of variables as much as possible.

• No name shadowing, including of predeclared identifiers, since it can often lead to subtle bugs, especially with errors. This rule does not apply to struct fields, since they are always used together with the name of the struct value, so there isn't any confusion.

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

• Prefer defining Foo.String and ParseFoo in terms of Foo.MarshalText and Foo.UnmarshalText correspondingly and not the other way around.

• Prefer to use named functions for goroutines.

• Program code lines should not be longer than one hundred (100) columns. For comments, see the text section below.

• Use linters. make go-lint.

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

Commenting

• See also the “Text, Including Comments” section below.

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

• Don't put identifiers into any kind of quotes.

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

• 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() {
          // …
  }
  

  When the implemented interface is unexported:

  // Unwrap implements the hidden wrapper interface for *fooError.
  func (err *fooError) Unwrap() (unwrapped error) {
          // …
  }
  

Formatting

• Decorate break, continue, return, and other terminating statements with empty lines unless it's the only statement in that block.

• Don't group type declarations together. Unlike with blocks of consts, where a iota may be used or where all constants belong to a certain type, there is no reason to group types.

• Group require.* blocks together with the presceding related statements, but separate from the following assert.* and unrelated requirements.

  val, ok := valMap[key]
  require.True(t, ok)
  require.NotNil(t, val)
  
  assert.Equal(t, expected, val)
  

• Use gofumpt --extra -s.

• Write slices of struct like this:

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

Naming

• 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.

• Name benchmarks and tests using the same convention as examples. For example:

  func TestFunction(t *testing.T) { /* … */ }
  func TestFunction_suffix(t *testing.T) { /* … */ }
  func TestType_Method(t *testing.T) { /* … */ }
  func TestType_Method_suffix(t *testing.T) { /* … */ }
  

• Name parameters in interface definitions:

  type Frobulator interface {
          Frobulate(f Foo, b Bar) (r Result, err error)
  }
  

• Name the deferred errors (e.g. when closing something) derr.

• Unused arguments in anonymous functions must be called _:

  v.onSuccess = func(_ int, msg string) {
          // …
  }
  

• Use named returns to improve readability of function signatures.

• When naming a file which defines an entity, use singular nouns, unless the entity is some form of a container for other entities:

  // File: client.go
  
  package foo
  
  type Client struct {
          // …
  }
  

  // File: clients.go
  
  package foo
  
  type Clients []*Client
  
  // …
  
  type ClientsWithCache struct {
          // …
  }
  

Testing

• Use assert.NoError and require.NoError instead of assert.Nil and require.Nil on errors.

• Use formatted helpers, like assert.Nilf or require.Nilf, instead of simple helpers when a formatted message is required.

• Use functions like require.Foo instead of assert.Foo when the test cannot continue if the condition is false.

Recommended Reading

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

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

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

Markdown

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

• Prefer triple-backtick preformatted code blocks to indented code blocks.

• Use asterisks and not underscores for bold and italic.

• Use either link references or link destinations only. Put all link reference definitions at the end of the second-level block.

Shell Scripting

• Avoid bashisms and GNUisms, prefer POSIX features only.

• Avoid spaces between patterns of the same case condition.

• export and readonly should be used separately from variable assignment, because otherwise failures in command substitutions won't stop the script. That is, do this:

  X="$( echo 42 )"
  export X
  

  And not this:

  # Bad!
  export X="$( echo 42 )"
  

• If a binary value is needed, use 0 for false, and 1 for true.

• Mark every variable that shouldn't change later as readonly.

• Prefer 'raw strings' to "double quoted strings" whenever possible.

• Put spaces within $( cmd ), $(( expr )), and { cmd; }.

• Put utility flags in the ASCII order and don't group them together. For example, ls -1 -A -q.

• Script code lines should not be longer than one hundred (100) columns. For comments, see the text section below.

• snake_case, not camelCase for variables. kebab-case for filenames.

• Start scripts with the following sections in the following order:

  1. Shebang.
  2. Some initial documentation (optional).
  3. Verbosity level parsing (optional).
  4. set options.

• UPPERCASE names for external exported variables, lowercase for local, unexported ones.

• Use set -e -f -u and also set -x in verbose mode.

• Use the "$var" form instead of the $var form, unless word splitting is required.

• When concatenating, always use the form with curly braces to prevent accidental bad variable names. That is, "${var}_tmp.txt" and not "$var_tmp.txt". The latter will try to lookup variable var_tmp.

• When concatenating, surround the whole string with quotes. That is, use this:

  dir="${TOP_DIR}/sub"
  

  And not this:

  # Bad!
  dir="${TOP_DIR}"/sub
  

Shell Conditionals

Guidelines and agreements for using command test, also known as [:

• For conditionals that check for equality against multiple values, prefer case instead of test.

• Prefer the != '' form instead of using -n to check if string is empty.

• Spell compound conditions with &&, ||, and ! outside of test instead of -a, -o, and ! inside of test correspondingly. The latter ones are pretty much deprecated in POSIX.

  See also: “Problems With the test Builtin: What Does -a Mean?”.

• Use = for strings and -eq for numbers to catch typing errors.

Text, Including Comments

• End sentences with appropriate punctuation.

• Headers should be written with all initial letters capitalized, except for references to variable names that start with a lowercase letter.

• Mark temporary todos—that is, todos that must be resolved or removed before publishing a change—with two exclamation signs:

  // TODO(usr1): !! Remove this debug before pushing!
  

  This makes it easier to find them both during development and during code review.

• Start sentences with a capital letter, unless the first word is a reference to a variable name that starts with a lowercase letter.

• 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.
  

YAML

• TODO(a.garipov): Define naming conventions for schema names in our OpenAPI YAML file. And just generally OpenAPI conventions.

• 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. YAML documents can get pretty deeply-nested.

• No extra indentation in multiline arrays:

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

• Prefer single quotes for strings to prevent accidental escaping, unless escaping is required or there are single quotes inside the string (e.g. for GitHub Actions).

• Use > for multiline strings, unless you need to keep the line breaks. Use | for multiline strings when you do.