thedumptruck/safe-golang

Safe Golang

Build highly predictable, robust, and performant Go applications with a "zero technical debt" policy.

Retrieval-First Development

Always verify standards against the reference documentation before implementing.

| Resource | URL / Path | |----------|------------| | Safety & Control Flow | ./references/safety.md | | Performance Patterns | ./references/performance.md | | Developer Experience | ./references/dx.md |

Review the relevant documentation when writing new logic or performing code reviews.

When to Use

• Writing new Go logic from scratch
• Refactoring existing Go code to improve safety or performance
• Reviewing Go PRs for code quality and standard adherence
• Optimizing memory allocations or hot paths
• Implementing strict error handling or boundary validation

Reference Documentation

• ./references/safety.md - Control flow limits, dynamic memory restrictions, assertions, errors
• ./references/performance.md - In-place initialization, batching strategies
• ./references/dx.md - Naming conventions, options structs, formatting limits, zero dependencies

Search: no recursion, context cancellation, sync.Pool, golangci-lint, options struct

Core Principles

Apply Safe Golang For

| Need | Example | |------|---------| | Predictable Execution | Bounded channels, bounded loops, timeout contexts | | Memory Stability | Pre-allocating at startup, sync.Pool, value types over pointers | | Operational Reliability | Explicitly wrapped errors, pair assertions | | Maintainability | Maximum 70 lines per function, max 100 columns per line, options structs |

Do NOT Use

• Unbounded loops or goroutines without a context.Context
• Dynamic memory allocations (make(), new()) in hot paths
• Deep indirection (** or pointers to interfaces)
• Third-party dependencies (unless explicitly approved, e.g., godotenv)

Quick Reference

Bounded Control Flow Pattern

// Always bound asynchronous or repeated operations
const maxTasks = 1000
ch := make(chan Task, maxTasks)

for {
    select {
    case <-ctx.Done():
        // Always handle cancellation
        return ctx.Err()
    default:
        if checkStatus() == "done" {
            return nil
        }
        time.Sleep(10 * time.Millisecond)
    }
}

Allocation-Free Hot Path

type Server struct {
    bufferPool sync.Pool
}

func NewServer() *Server {
    return &Server{
        bufferPool: sync.Pool{
            New: func() any {
                b := make([]byte, 1024*1024)
                return &b
            },
        },
    }
}

func (s *Server) process(data []byte) {
    // Acquire from pool instead of allocating
    bufPtr := s.bufferPool.Get().(*[]byte)
    defer s.bufferPool.Put(bufPtr)
    
    // ...
}

Critical Rules

1. No Recursion or goto - Keep control flow simple and execution bounds completely static.
2. Fixed Upper Bounds - All loops and channels must be bounded (e.g. by size or context timeouts).
3. No Dynamic Memory After Init - Allocate all significant memory at startup. Use sync.Pool for dynamic reuse.
4. Short Functions - Hard limit of 70 lines per function. Push ifs up, push fors down.
5. Check All Returns - Never ignore errors with _. Handle or wrap every returned error.
6. Explicit Panics Only - Panic only for programmer errors/broken invariants. Use standard errors for operational issues.
7. Limit Indirection - Use at most one level of pointer indirection. Prefer value types.
8. Options Structs - Use explicit options structs for configuration instead of multiple boolean arguments.
9. Zero Dependencies - Strictly avoid third-party dependencies outside the standard library.
10. Strict Naming - Add units or qualifiers at the end of variables (e.g., timeoutMs, latencyMaxMs).

Anti-Patterns (NEVER)

• Ignoring errors (_ = ...)
• Using init() for magic initialization or global mutable state
• Using reflect for runtime type manipulation
• Passing double pointers (e.g. **Node)
• Creating unbounded channels (make(chan T)) or unbound loops
• Making network requests without a timeout or context

Credits

• TIGER_STYLE.md