go-coding-standards

Go Coding Standards

Idiomatic Go conventions grounded in Effective Go, Go Code Review Comments, and production-proven idioms. All code MUST pass goimports, go vet, and staticcheck (or golangci-lint run) without errors.

1. Import Ordering

Group imports in this order, separated by blank lines:

import (
    // 1. Standard library
    "context"
    "fmt"
    "net/http"

    // 2. External packages
    "github.com/gorilla/mux"
    "log/slog"

    // 3. Internal/project packages
    "github.com/myorg/myproject/internal/service"
)

NEVER use dot imports. Use aliasing only to resolve conflicts.

2. Naming Conventions

Packages

• Short, lowercase, single-word names. No underscores, no camelCase.
• Name should describe what the package provides, not what it contains.
• Avoid generic names: util, common, helpers, misc, base.

Functions & Methods

• MixedCaps (exported) or mixedCaps (unexported). No underscores except in test files.
• Getters: use Name(), NOT GetName(). Setters: use SetName().
• Constructors: NewFoo() returns *Foo. If only one type in package: New().

Variables

• Short names in tight scopes: i, n, err, ctx.
• Descriptive names for wider scopes: userCount, retryTimeout.
• Prefix unexported package-level globals with _: var _defaultTimeout = 5 * time.Second.
• Do NOT shadow built-in identifiers (error, len, cap, new, make, close).

Interfaces

• Single-method interfaces: method name + -er suffix (Reader, Writer, Closer).
• Define interfaces where they are consumed, not where they are implemented.

3. Variable Declarations

Top-level

Use var for top-level declarations. Do NOT specify type when it matches the expression:

// ✅ Good
var _defaultPort = 8080
var _logger = slog.Default()

// ❌ Bad — redundant type
var _defaultPort int = 8080

Local

• Prefer := for local variables.
• Use var only when zero-value initialization is intentional and meaningful.