go-style-guide.md

Go style guide

In order to keep our code looking good with lots of programmers working on it, it helps to have a "style guide", so all the code generally looks quite similar. This doesn't mean there is only one "right way" to write code, or even that this standard is better than your style. But if we agree to a number of stylistic practices, it makes it much easier to read and modify new code. Please feel free to make suggestions if there's something you would like to add or modify.

We expect all contributors to be familiar with Effective Go (and it's recommended reading for all Go programmers anyways). Additionally, we generally agree with the suggestions in Uber's style guide and use that as a starting point.

Code Structure

Perhaps more key for code readability than good commenting is having the right structure. As a rule of thumb, try to write in a logical order of importance, taking a little time to think how to order and divide the code such that someone could scroll down and understand the functionality of it just as well as you do. A loose example of such order would be:

• Constants, global and package-level variables.
• Main struct definition.
• Options (only if they are seen as critical to the struct else they should be placed in another file).
• Initialization/start and stop of the service functions.
• Public functions (in order of most important).
• Private/helper functions.
• Auxiliary structs and function (can also be above private functions or in a separate file).

General

• Use gofumpt to format all code upon saving it (or run make format).
• Think about documentation, and try to leave godoc comments, when it will help new developers.
• Every package should have a high level doc.go file to describe the purpose of that package, its main functions, and any other relevant information.
• Applications (e.g. clis/servers) should panic on unexpected unrecoverable errors and print a stack trace.

Comments

• Use a space after the comment deliminter (ex. // your comment).

• Many comments are not sentences. These should begin with a lower case letter and end without a period.

• Conversely, sentences in comments should be sentenced-cased and end with a period.

• Comments should explain why something is being done rather than what the code is doing. For example:

  The comments in

   // assign a variable foo
   f := foo
   // assign f to b
   b := f
  

  have little value, but the following is more useful:

   f := foo
   // we copy the variable f because we want to preserve the state at time of initialization
   b := f
  

Linting

• Run make lint-fix to fix any linting errors.

Various

• Functions that return functions should have the suffix Fn.

• Names should not stutter. For example, a struct generally shouldn’t have a field named after itself; e.g., this shouldn't occur:

   type middleware struct {
   	middleware Middleware
   }

• Acronyms are all capitalized, like "RPC", "gRPC", "API". "MyID", rather than "MyId".

• Whenever it is safe to use Go's built-in error instantiation functions (as opposed to Cosmos SDK's error instantiation functions), prefer errors.New() instead of fmt.Errorf() unless you're actually using the format feature with arguments.

Importing libraries

• Use goimports.

• Separate imports into blocks: one for the standard lib, one for external libs and one for application libs. For example:

   import (
   	// standard library imports
   	"fmt"
   	"testing"
   				
   	// external library imports
   	"github.com/stretchr/testify/require"
   	abci "github.com/tendermint/tendermint/abci/types"
   				
   	// ibc-go library imports
   	"github.com/cosmos/ibc-go/modules/core/23-commitment/types"
   )

Dependencies

• Dependencies should be pinned by a release tag, or specific commit, to avoid breaking go get when external dependencies are updated.
• Refer to the contributing document for more details.

Testing

• Make use of table driven testing where possible and not-cumbersome. Read this blog post for more information. See the tests for Transfer for an example.
• Make use of Testify assert and require.
• When using mocks, it is recommended to use Testify mock along with Mockery for autogeneration.

Errors

• Ensure that errors are concise, clear and traceable.

• Depending on the context, use either cosmossdk.io/errors or stdlib error packages.

• For wrapping errors, use fmt.Errorf() with %w.

• Panic is appropriate when an internal invariant of a system is broken, while all other cases (in particular, incorrect or invalid usage) should return errors.

• Error messages should be formatted as following:

   sdkerrors.Wrapf(
   	<most specific error type possible>,
   	"<optional text description ended by colon and space>expected %s, got %s",
   	<value 1>,
   	<value 2>
   )