Go Style Core Principles

Normative: This guidance is required per Google's canonical Go style guide.

Style Principles (Priority Order)

1. Clarity

• What: Use descriptive names, helpful comments, and efficient organization
• Why: Add commentary explaining rationale, especially for nuances
• View clarity through the reader's lens, not the author's
• Code should be easy to read, not easy to write

// Good: Clear purpose
func (c *Config) WriteTo(w io.Writer) (int64, error)

// Bad: Unclear, repeats receiver
func (c *Config) WriteConfigTo(w io.Writer) (int64, error)

2. Simplicity

• Is easy to read top to bottom
• Does not assume prior knowledge
• Has no unnecessary abstraction levels
• Has comments explaining "why", not "what"
• May be mutually exclusive with "clever" code

1. Core language constructs (channel, slice, map, loop, struct)
2. Standard library tools (http client, template engine)
3. Core libraries before new dependencies

3. Concision

• Avoid repetitive code
• Avoid extraneous syntax
• Avoid unnecessary abstraction
• Use table-driven tests to factor out common code

// Good: Common idiom, high signal
if err := doSomething(); err != nil {
    return err
}

// Good: Signal boost for unusual case
if err := doSomething(); err == nil { // if NO error
    // ...
}

4. Maintainability

• Is easy for future programmers to modify correctly
• Has APIs that grow gracefully
• Uses predictable names (same concept = same name)
• Minimizes dependencies
• Has comprehensive tests with clear diagnostics

// Bad: Critical detail hidden
if user, err = db.UserByID(userID); err != nil { // = vs :=

// Good: Explicit and clear
u, err := db.UserByID(userID)
if err != nil {
    return fmt.Errorf("invalid origin user: %s", err)
}
user = u

5. Consistency

• Package-level consistency is most important
• When ties occur, break in favor of consistency
• Never override documented style principles for consistency

Formatting

gofmt is Required

gofmt

# Format a file
gofmt -w myfile.go

# Format all files in directory
gofmt -w .

Parentheses

Source: Effective Go

if

for

switch

x<<8 + y<<16

MixedCaps (Camel Case)

MixedCaps

mixedCaps

// Good
MaxLength    // exported constant
maxLength    // unexported constant
userID       // variable

// Bad
MAX_LENGTH   // no snake_case
max_length   // no underscores

• Test function names may use underscores:

  TestFoo_Bar

• Generated code interoperating with OS/cgo

Line Length

Combined: Google + Uber + Go Wiki CodeReviewComments guidance

• If a line feels too long, refactor rather than just wrap
• Don't split before indentation changes (function declarations, conditionals)
• Don't split long strings (URLs) into multiple lines
• When splitting, put all arguments on their own lines
• If it's already as short as practical, let it remain long

Advisory: Go Wiki CodeReviewComments

// Bad: Arbitrary mid-line break
func (s *Store) GetUser(ctx context.Context,
    id string) (*User, error) {

// Good: All arguments on own lines
func (s *Store) GetUser(
    ctx context.Context,
    id string,
) (*User, error) {

Local Consistency

• %s

  vs

  %v

  for error formatting
• Buffered channels vs mutexes

• Line length restrictions
• Assertion-based testing libraries

Reduce Nesting

Source: Uber Go Style Guide

// Bad: Deeply nested
for _, v := range data {
    if v.F1 == 1 {
        v = process(v)
        if err := v.Call(); err == nil {
            v.Send()
        } else {
            return err
        }
    } else {
        log.Printf("Invalid v: %v", v)
    }
}

// Good: Flat structure with early returns
for _, v := range data {
    if v.F1 != 1 {
        log.Printf("Invalid v: %v", v)
        continue
    }

    v = process(v)
    if err := v.Call(); err != nil {
        return err
    }
    v.Send()
}

Unnecessary Else

Source: Uber Go Style Guide

// Bad: Setting in both branches
var a int
if b {
    a = 100
} else {
    a = 10
}

// Good: Default + override
a := 10
if b {
    a = 100
}

Naked Returns

Advisory: Go Wiki CodeReviewComments

return

func split(sum int) (x, y int) {
    x = sum * 4 / 9
    y = sum - x
    return  // returns x, y
}

Guidelines for Naked Returns

• OK in small functions: Naked returns are fine in functions that are just a handful of lines
• Be explicit in medium+ functions: Once a function grows to medium size, be explicit with return values for clarity
• Don't name results just for naked returns: Clarity of documentation is always more important than saving a line or two. Don't name result parameters just because it enables naked returns

// Good: Small function, naked return is clear
func minMax(a, b int) (min, max int) {
    if a < b {
        min, max = a, b
    } else {
        min, max = b, a
    }
    return
}

// Good: Larger function, explicit return
func processData(data []byte) (result []byte, err error) {
    result = make([]byte, 0, len(data))

    for _, b := range data {
        if b == 0 {
            return nil, errors.New("null byte in data")
        }
        result = append(result, transform(b))
    }

    return result, nil  // explicit: clearer in longer functions
}

Quick Reference

See Also

• For naming conventions:

  go-naming

• For error handling patterns:

  go-error-handling

• For documentation guidelines:

  go-documentation

• For testing best practices:

  go-testing

• For defensive programming:

  go-defensive

• For performance optimization:

  go-performance

• For linting and static analysis:

  go-linting