go-coding-standards

Go Coding Standards

Quick Navigation: Level 1: Quick Start (5 min) → Level 2: Implementation (30 min) → Level 3: Mastery (Extended)

Level 1: Quick Start (<2,000 tokens, 5 minutes)

Core Principles

1. Idiomatic Go: Write code that follows Go idioms - simple, clear, and effective
2. Explicit Errors: Return errors explicitly, handle them properly, no exceptions
3. Interfaces: Accept interfaces, return concrete types
4. Concurrency: Goroutines and channels for concurrent operations
5. Testing: Table-driven tests with >80% coverage

Essential Checklist

• Formatting: Code formatted with gofmt, imports organized with goimports
• Naming: Follow Go conventions (MixedCaps, camelCase, short names in limited scope)
• Error Handling: All errors checked and wrapped with context
• Testing: _test.go files with table-driven tests, benchmarks
• Documentation: Package and exported function documentation
• Modules: go.mod with semantic versioning, tidy dependencies
• Linting: Pass golangci-lint with strict configuration
• Security: Input validation, no hardcoded secrets, secure defaults

Quick Example

// Package auth provides user authentication services.
package auth

import (
	"context"
	"errors"
	"fmt"
)

var (
	// ErrInvalidCredentials indicates authentication failure.
	ErrInvalidCredentials = errors.New("invalid credentials")
	// ErrUserNotFound indicates user does not exist.
	ErrUserNotFound = errors.New("user not found")
)

// User represents an authenticated user.
type User struct {
	ID       string
	Username string
	Email    string
}

// Repository defines user storage operations.
type Repository interface {
	FindByUsername(ctx context.Context, username string) (*User, error)
	VerifyPassword(ctx context.Context, userID, password string) bool
}

// Service handles authentication operations.
type Service struct {
	repo Repository
}

// NewService creates a new authentication service.
func NewService(repo Repository) *Service {
	return &Service{repo: repo}
}

// Authenticate verifies credentials and returns the authenticated user.
//
// Returns ErrInvalidCredentials if authentication fails,
// ErrUserNotFound if user doesn't exist, or wrapped errors for other failures.
func (s *Service) Authenticate(ctx context.Context, username, password string) (*User, error) {
	if username == "" || password == "" {
		return nil, fmt.Errorf("username and password required")
	}

	user, err := s.repo.FindByUsername(ctx, username)
	if err != nil {
		if errors.Is(err, ErrUserNotFound) {
			return nil, ErrInvalidCredentials // Don't reveal user existence
		}
		return nil, fmt.Errorf("find user: %w", err)
	}

	if !s.repo.VerifyPassword(ctx, user.ID, password) {
		return nil, ErrInvalidCredentials
	}

	return user, nil
}