Go Pedantry

// BAD -- error chain is destroyed, errors.Is() will not work
func GetUser(ctx context.Context, id string) (*User, error) {
    user, err := db.QueryUser(ctx, id)
    if err != nil {
        return nil, fmt.Errorf("failed to get user %s: %s", id, err.Error())
    }
    return user, nil
}

// BAD -- %v also destroys the chain
func GetUser(ctx context.Context, id string) (*User, error) {
    user, err := db.QueryUser(ctx, id)
    if err != nil {
        return nil, fmt.Errorf("failed to get user %s: %v", id, err)
    }
    return user, nil
}

// GOOD -- %w preserves the error chain
func GetUser(ctx context.Context, id string) (*User, error) {
    user, err := db.QueryUser(ctx, id)
    if err != nil {
        return nil, fmt.Errorf("getting user %s: %w", id, err)
    }
    return user, nil
}

// Now callers can inspect the error chain:
user, err := GetUser(ctx, "usr_123")
if errors.Is(err, sql.ErrNoRows) {
    // handle not found
}

// GOOD -- exported, Err prefix, PascalCase after prefix
var (
    ErrNotFound      = errors.New("not found")
    ErrAlreadyExists = errors.New("already exists")
    ErrInvalidInput  = errors.New("invalid input")
    ErrUnauthorized  = errors.New("unauthorized")
    ErrRateLimited   = errors.New("rate limited")
)

// BAD -- every one of these violates the convention
var (
    NotFoundError = errors.New("not found")     // wrong: no Err prefix
    errnotfound   = errors.New("not found")     // wrong: unexported + no camelCase
    NOT_FOUND     = errors.New("not found")     // wrong: not Go convention
    UserNotFound  = errors.New("user not found") // wrong: no Err prefix
)

// GOOD
type ErrValidation struct {
    Field   string
    Message string
}

func (e *ErrValidation) Error() string {
    return fmt.Sprintf("validation error on %s: %s", e.Field, e.Message)
}

// BAD -- returning an interface hides the concrete type
func NewUserService(db Database) UserServiceInterface {
    return &UserService{db: db}
}

// BAD -- accepting a concrete type prevents testing and alternative implementations
func ProcessOrder(service *StripeService, order *Order) error {
    return service.Charge(order.Total)
}

// GOOD -- accept interface, return struct
func NewUserService(db UserRepository) *UserService {
    return &UserService{db: db}
}

// GOOD -- accept interface for the dependency
func ProcessOrder(payment PaymentProcessor, order *Order) error {
    return payment.Charge(order.Total)
}

// BAD -- too many methods, too specific
type UserManager interface {
    GetUser(ctx context.Context, id string) (*User, error)
    CreateUser(ctx context.Context, input CreateUserInput) (*User, error)
    UpdateUser(ctx context.Context, id string, input UpdateUserInput) (*User, error)
    DeleteUser(ctx context.Context, id string) error
    ListUsers(ctx context.Context, opts ListOptions) ([]*User, error)
    SearchUsers(ctx context.Context, query string) ([]*User, error)
    CountUsers(ctx context.Context) (int, error)
}

// GOOD -- small, focused interfaces
type UserReader interface {
    GetUser(ctx context.Context, id string) (*User, error)
}

type UserWriter interface {
    CreateUser(ctx context.Context, input CreateUserInput) (*User, error)
    UpdateUser(ctx context.Context, id string, input UpdateUserInput) (*User, error)
    DeleteUser(ctx context.Context, id string) error
}

type UserLister interface {
    ListUsers(ctx context.Context, opts ListOptions) ([]*User, error)
}

// BAD -- interface defined in the implementation package
// package database
type UserStore interface {
    Get(ctx context.Context, id string) (*User, error)
    Save(ctx context.Context, user *User) error
}

type PostgresUserStore struct { ... }

// GOOD -- interface defined where it is used
// package handler (the consumer)
type UserGetter interface {
    Get(ctx context.Context, id string) (*User, error)
}

type GetUserHandler struct {
    users UserGetter  // accepts interface
}

// package database (the implementation)
type PostgresUserStore struct { ... }

func (s *PostgresUserStore) Get(ctx context.Context, id string) (*User, error) { ... }
// PostgresUserStore satisfies handler.UserGetter without importing it

// BAD -- package naming violations
package userService        // camelCase
package user_service       // underscores
package utils              // meaningless
package common             // meaningless
package helpers            // meaningless

// In user package:
type UserService struct{}  // stutters: user.UserService
type UserRepository struct{} // stutters: user.UserRepository

// GOOD -- clean package names
package user

type Service struct{}     // user.Service -- reads naturally
type Repository struct{}  // user.Repository -- no stutter

package auth
type Token struct{}       // auth.Token
type Middleware struct{}   // auth.Middleware

package order
type Processor struct{}   // order.Processor

// BAD -- no logical grouping
type Server struct {
    addr          string
    logger        *slog.Logger
    TLS           bool
    db            *sql.DB
    Port          int
    Host          string
    readTimeout   time.Duration
    cache         *Cache
    WriteTimeout  time.Duration
    maxConns      int
}

// GOOD -- grouped by purpose, exported first within groups, tags consistent
type Server struct {
    // Configuration (exported)
    Host         string        `json:"host" yaml:"host"`
    Port         int           `json:"port" yaml:"port"`
    TLS          bool          `json:"tls"  yaml:"tls"`
    ReadTimeout  time.Duration `json:"read_timeout" yaml:"read_timeout"`
    WriteTimeout time.Duration `json:"write_timeout" yaml:"write_timeout"`
    MaxConns     int           `json:"max_conns" yaml:"max_conns"`

    // Dependencies (unexported)
    db     *sql.DB
    cache  *Cache
    logger *slog.Logger
}