go

Go Best Practices

This guide outlines our team's definitive Go coding standards, emphasizing clarity, simplicity, performance, and maintainability. Adhere to these principles to ensure a consistent, high-quality codebase that aligns with Google's Go Style Guide.

1. Code Organization & Structure

Prioritize clarity and discoverability. Structure your projects logically, making it easy for new team members to understand the codebase.

Package Naming & Purpose

Packages must have short, lowercase names that clearly describe their single purpose. Avoid generic names like util or common.

❌ BAD:

// myproject/utils/string_helpers.go
package utils // Too generic, doesn't describe specific utility

func SanitizeString(s string) string { /* ... */ }

✅ GOOD:

// myproject/text/sanitizer.go
package text // Clear domain, specific functionality

func Sanitize(s string) string { /* ... */ }

internal Package for Encapsulation

Always use the internal directory for code that should not be imported by other projects or external modules. This enforces strong encapsulation and prevents unintended dependencies.

❌ BAD:

// myproject/service/auth.go (Exposes internal logic to external consumers)
package service

type AuthService struct { /* ... */ }

✅ GOOD:

// myproject/internal/auth/service.go (Only importable by modules within 'myproject')
package auth

type Service struct { /* ... */ }

2. Error Handling

Handle errors explicitly and provide actionable context. Never ignore errors. Use errors.Is and errors.As for robust error inspection.

Wrap Errors with Context

Always wrap errors to add context, making debugging easier and preserving the error chain. Use %w with fmt.Errorf to enable errors.Is and errors.As.

❌ BAD:

if err := db.Save(user); err != nil {
    return fmt.Errorf("failed to save user: %v", err) // Loses original error type
}

✅ GOOD:

if err := db.Save(user); err != nil {
    return fmt.Errorf("failed to save user %s: %w", user.ID, err) // Original error preserved
}