go-idioms

Go Idioms

Core Philosophy

1. Simplicity over cleverness: clear, obvious code over clever abstractions
2. Explicit over implicit: make intentions visible through code structure
3. Composition over inheritance: build through interface composition
4. Error values over exceptions: handle errors as values

Error Handling

Sentinel Errors and Wrapping

var ErrNotFound = errors.New("not found")

// Wrap with context — %w at the end
if err != nil {
    return fmt.Errorf("fetching user %d: %w", userID, err)
}

if errors.Is(err, ErrNotFound) { /* handle */ }

var valErr *ValidationError
if errors.As(err, &valErr) { /* access valErr.Field */ }

Structured Errors

type AppError struct {
    Code    string         `json:"code"`
    Message string         `json:"message"`
    Err     error          `json:"-"`
}

func (e *AppError) Error() string { return e.Message }
func (e *AppError) Unwrap() error { return e.Err }

Rules

• Never ignore errors — handle or propagate explicitly
• Add context when wrapping — include relevant identifiers
• Handle once — either log or wrap+return, not both
• Panic only for programming errors, never for user input

Naming Conventions

// Packages: short, lowercase, no underscores
package user   // good
package util   // bad — too generic

// Avoid repetition: user.Service not user.UserService
package user
type Service struct{}   // user.Service
func New() *Service     // user.New()

// Interfaces: single-method = "er" suffix
type Reader interface { Read(p []byte) (int, error) }
type Repository interface {
    Save(ctx context.Context, entity *Entity) error
    Delete(ctx context.Context, id string) error
}

// Variables
userID    // good        ctx       // good
uID       // bad         context   // bad (shadows pkg)
isValid   // clear bool  valid     // less clear

Interface Design

// Accept interfaces, return structs
func NewService(repo Repository) *Service { return &Service{repo: repo} }
func NewRepository(db *sql.DB) *PostgresRepo { return &PostgresRepo{db: db} }

// Small, composable interfaces
type Reader interface { Read(ctx context.Context, id string) (*Data, error) }
type Writer interface { Write(ctx context.Context, data *Data) error }
type ReadWriter interface { Reader; Writer }

// Compile-time compliance check
var _ Repository = (*PostgresRepo)(nil)