go.md

Go Development Conventions

Introduction

This guide documents development conventions for Go at source{d}. Check general conventions for language-independent conventions that are also applicable for Go projects.

Supported Go Versions

• Our libraries support latest two stable major versions of Go (currently: 1.11.x and 1.12.x). Both versions should be included in Travis CI.
  • Some of our libraries may support more versions, specially when there is wide-adoption outside source{d}, (e.g. go-git which currently supports three.
• Our applications support only latest stable Go version (1.12.x).

Dependency Management

• If your project is a library:
  • Use gopkg.in to provide versioned imports.
• If your project is an application:
  • Use modules to manage dependencies.
  • Do not check in the vendor directory into git.

Build System

• If your project requires fetching or building dependencies, implement that in the dependencies rule.
• If binaries can be built, do so in the packages rule. Note that src-d/ci provides that rule by default.

Code Generation

• All generated code should be always processed by gofmt.
• Generated code should have a // Code generated ... DO NOT EDIT. comment before the package clause, but not attached to it (see convention).

Docker

• If you use alpine-based images, your binaries need to be built with CGO_ENABLED=0. src-d/ci does this by default. If your project uses cgo, you will have to use alpine for the build of binaries for Docker.

Testing

• Use testify.
• Use suites to share setup/teardown code among related tests. When testing multiple methods of the same struct, you generally want to start with a suite. Some cases, such as table-driven tests, are better handled with subtests though.

Error handling

• Use src-d/go-errors.

Logging

• Use logging in your applications.
• Use src-d/go-log.

Other libraries

• We use protobuf extensively and gogo is our preferred library.

Best Practices

• Use gofmt, goimports, go vet.
• Follow community well-established best practices: Effective Go and Go Code Review Comments.
• Sourcerers use additional linters such as golint and megacheck.

Group code blocks with blank lines

In order to improve readability, we use single blank lines to separate logic blocks of code inside functions.

A blank line is usually added after the end of any control structure, too.

Naming

• Prefer full names (e.g. Repository, not Repo).

CLI

• Put sources for your executable commands in cmd/<command-name>/, with the main function in cmd/<command-name>/main.go.
• We use go-flags extensively for CLI options parsing.
• Implement commands in a subpackage (example).

Configuration

• Use environment variables for configuration.
• You can use the envconfig package to parse the environment into a configuration struct.