golang-rules

Go Coding Rules

Coding Style

Immutability (CRITICAL)

ALWAYS create new objects, NEVER mutate existing ones:

// Pseudocode
WRONG:  modify(original, field, value) -> changes original in-place
CORRECT: update(original, field, value) -> returns new copy with change

Rationale: Immutable data prevents hidden side effects, makes debugging easier, and enables safe concurrency.

File Organization

MANY SMALL FILES > FEW LARGE FILES:

• High cohesion, low coupling
• 200-400 lines typical, 800 max
• Extract utilities from large modules
• Organize by feature/domain, not by type

Formatting

• gofmt and goimports are mandatory -- no style debates

Design Principles

• Accept interfaces, return structs
• Keep interfaces small (1-3 methods)

Error Handling

ALWAYS handle errors comprehensively:

• Handle errors explicitly at every level
• Provide user-friendly error messages in UI-facing code
• Log detailed error context on the server side
• Never silently swallow errors

Always wrap errors with context:

if err != nil {
    return fmt.Errorf("failed to create user: %w", err)
}

Input Validation

ALWAYS validate at system boundaries:

• Validate all user input before processing
• Use schema-based validation where available
• Fail fast with clear error messages
• Never trust external data (API responses, user input, file content)

Code Quality Checklist

Before marking work complete:

• Code is readable and well-named
• Functions are small (<50 lines)
• Files are focused (<800 lines)
• No deep nesting (>4 levels)
• Proper error handling
• No hardcoded values (use constants or config)
• No mutation (immutable patterns used)

Patterns

Skeleton Projects

When implementing new functionality:

1. Search for battle-tested skeleton projects
2. Evaluate options for security, extensibility, relevance
3. Clone best match as foundation
4. Iterate within proven structure

Repository Pattern

Encapsulate data access behind a consistent interface:

• Define standard operations: findAll, findById, create, update, delete
• Concrete implementations handle storage details (database, API, file, etc.)
• Business logic depends on the abstract interface, not the storage mechanism
• Enables easy swapping of data sources and simplifies testing with mocks