Skip to main content
Version: 0.8.0

Coding Guidelines

The basics​

GO as a language provides a build in formatter for the code: gofmt. The project uses the predefined format as implemented in gofmt. That means tabs and not spaces etc. Read the Effective GO page for further details. Before creating a pull request make sure the code at least is formatted using gofmt.

Beside the effective GO guide follow the recommendations from the CodeReviewComments wiki page. The wiki provides a good collection of comments from code reviews. Most of the comments will be checked in the automated checks described below.

When using an IDE, like GoLand or Visual Studio Code, use the builtin options. Most IDEs will provide an extensive list of checks or formatting options that help formatting and point out code issues. See IDE setup for a basic setup for the GoLand IDE.

Automated checks​

Not all code will be written using an IDE. Even between contributors the settings might not be the same in all installs. To help keep code formatted consistently a lint tool is part of the code approval.

There are a large number of lint tools are available for Go. Most of the lint tools only check one specific thing. Some of the tools will aggregate a number of linters and provide an overview of all the issues found. For the project we have chosen the golangci-lint tool. The tool can be run locally and will be integrated into the GitHub PR flow.

Installing and running locally​

Depending on your development system the instructions might differ slightly. Follow the installation instructions provided by the project.

After the tool is installed you can run it using the standard command line:

golangci-lint run

The projects still generate a number of warnings. The high impact warnings have been fixed or ignored via comments, see False positives.

If you have been working on a new feature or a bug you only want to check the files that have changed. You can run the tool with the option --new or --new-from-rev option. The --new option will only check uncommitted files. The --new-from-rev option will check changes against a specific committed revision.

# for uncommitted changes
golangci-lint run --new
# for committed changes against a revision
golangci-lint run --new-from-rev=origin/master

The make integration checks two locations for the executable and uses the --new command line option.

  • go env GOPATH)/bin/
  • ./bin/ (relative to the project)

The make target is lint:

make lint

See the golangci-lint product documentation for more options and information on how to run the tool.

Configuration​

A predefined configuration is provided for the two projects that use them:

The web interface is a javascript project and the scheduler interface only has generated Go code and thus do not use it.

Integration in pull requests​

The planning is to integrate the golangci-lint check into the GitHub PR flow.

False positives​

Tools are never 100% correct and neither is this one. Certain issue are too hard to correct or are not important enough to fix.

The tool allows adding a comment to the code to ignore the issue. These comments should be used sparingly as they could hide issues. If they are used they should be accompanied by a comment to explain why they are used.

	var s1 = "ignored by all linters" //nolint
	var s2 = "ignored by the linter unused" //nolint:unused

Using the nolint comment without a specific linter is discouraged.

GoLand IDE setup​

GoLand has a number of checks turned on by default. These defaults already provide a good coverage and mark a lot of issues found by the linters as issues. To extend the coverage further and help mark issues proactively check the following settings and change them to the settings as per the screenshots.

Editor preferences​

Open the preferences pane and go to: Editor -> Code Style -> Go. There are three tabs to configure, the first two are crucial to comply with the basic rules from gofmt and goimports:

Tabstabs
Importsimports
Otherother

Inspections​

The default inspections except for one that helps highlight shadowing variables.

inspections