STYLE.md

CockroachDB Style guide

Go Code

We're following the Google Go Code Review fairly closely. In particular, you want to watch out for proper punctuation and capitalization in comments. We use two-space indents in non-Go code (in Go, we follow gofmt which indents with tabs).

Line Length

Format your code assuming it will be read in a window 100 columns wide. Wrap code at 100 characters and comments at 80 unless doing so makes the code less legible.

Wrapping Function Signatures

When wrapping function signatures that do not fit on one line, put the name, arguments, and return types on separate lines, with the closing ) at the same indentation as func (this helps visually separate the indented arguments from the indented function body). Example:

func (s *someType) myFunctionName(
    arg1 somepackage.SomeArgType, arg2 int, arg3 somepackage.SomeOtherType,
) (somepackage.SomeReturnType, error) {
    ...
}

If the arguments list is too long to fit on a single line, switch to one argument per line:

func (s *someType) myFunctionName(
    arg1 somepackage.SomeArgType,
    arg2 int,
    arg3 somepackage.SomeOtherType,
) (somepackage.SomeReturnType, error) {
    ...
}

If the return types need to be wrapped, use the same rules:

func (s *someType) myFunctionName(
    arg1 somepackage.SomeArgType, arg2 somepackage.SomeOtherType,
) (
    somepackage.SomeReturnType,
    somepackage.SomeOtherType,
    error,
) {
    ...
}

Exception when omitting repeated types for consecutive arguments: short and related arguments (e.g. start, end int64) should either go on the same line or the type should be repeated on each line -- no argument should appear by itself on a line with no type (confusing and brittle when edited).

Protobuf IDLs

In order to ensure on-the-wire and on-disk compatibility, and avoid confusing, unexpected serialization errors (or worse, correctness errors):

Never remove (or comment out) a field from a proto or change its type in place.

Instead, prefix unused fields with OBSOLETE_.

Removing or commenting out a field could allow the field ID to be accidentally reused -- leaving it lets the generator ensure that field IDs remain unique.

NB: In theory, a proto that is never written to the network or disk can ignore this rule. In practice, following it anyway is probably safer and any exceptions should be met with strict scrutiny in code review.

When deprecating a message field, it is safe to also change the type to bytes so that the message definition can be deleted.