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

• 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)

• 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

• 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
    // ...
}

• 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

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

Source: Effective Go

if

for

switch

x<<8 + y<<16

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

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) {

• %s

  vs

  %v

  for error formatting
• Buffered channels vs mutexes

• Line length restrictions
• Assertion-based testing libraries

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()
}

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
}

Advisory: Go Wiki CodeReviewComments

return

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

• 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
}

• 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