idiomatic-go

Idiomatic Go

Write Go code that follows community conventions, leveraging interfaces, struct embedding, and proper package organization for clean, maintainable projects.

When to Use

• Starting a new Go project or package
• Designing interfaces and struct hierarchies
• Choosing between value and pointer receivers
• Organizing packages and project layout
• Reviewing Go code for idiom violations

Core Patterns

Pattern 1: Interface Design

Define small interfaces at the point of consumption, not at the implementation site. The Go proverb: "The bigger the interface, the weaker the abstraction."

// GOOD: small, focused interfaces defined by the consumer
package storage

// Reader is defined where it is used, not where it is implemented.
type Reader interface {
    Read(ctx context.Context, key string) ([]byte, error)
}

func NewCache(reader Reader, ttl time.Duration) *Cache {
    return &Cache{reader: reader, ttl: ttl}
}

// Accept interfaces, return structs
func ProcessData(r io.Reader) (*Result, error) {
    data, err := io.ReadAll(r)
    if err != nil {
        return nil, fmt.Errorf("reading data: %w", err)
    }
    return &Result{Data: data}, nil
}

Pattern 2: Struct Embedding

Embed types to compose behavior without inheritance. Embedding promotes the embedded type's methods to the outer struct.

type Logger struct {
    prefix string
}

func (l *Logger) Log(msg string) {
    fmt.Printf("[%s] %s\n", l.prefix, msg)
}

type Server struct {
    Logger  // embed Logger -- Server now has a Log method
    addr string
}

func NewServer(addr string) *Server {
    return &Server{
        Logger: Logger{prefix: "server"},
        addr:   addr,
    }
}

// Usage
s := NewServer(":8080")
s.Log("starting") // promoted from Logger

Pattern 3: Receiver Methods -- Value vs Pointer

Use pointer receivers when the method mutates state or the struct is large. Use value receivers for small, immutable types.

// Value receiver: small, immutable, safe to copy
type Point struct {
    X, Y float64
}

func (p Point) Distance(other Point) float64 {
    dx := p.X - other.X
    dy := p.Y - other.Y
    return math.Sqrt(dx*dx + dy*dy)
}

// Pointer receiver: mutates state
type Counter struct {
    mu    sync.Mutex
    count int64
}

func (c *Counter) Increment() {
    c.mu.Lock()
    defer c.mu.Unlock()
    c.count++
}

func (c *Counter) Value() int64 {
    c.mu.Lock()
    defer c.mu.Unlock()
    return c.count
}