go-pedantry

Go Is Opinionated -- So Are We

Go is a language that already has strong opinions: gofmt, short variable names, explicit error handling, no exceptions. But the language's opinions stop at syntax. How you wrap errors, design interfaces, name packages, order struct fields, and configure your linter -- these are decisions Go leaves to you. This skill makes those decisions for you, because inconsistency in these areas is what turns a Go codebase from clean to chaotic.

Error Wrapping: Always %w, Never %s or %v

When wrapping an error with fmt.Errorf, ALWAYS use %w. This preserves the error chain so that errors.Is() and errors.As() work. Using %s or %v converts the error to a string and destroys the chain. This is not a style preference -- it is the difference between errors that can be programmatically handled and errors that can only be logged.

// 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
}

Error message conventions:

• Start with a lowercase verb in gerund form: "getting user", "parsing config", "connecting to database"
• Do NOT start with "failed to" or "error" -- the fact that it is an error is already clear from the context
• Add identifying information: IDs, names, paths -- whatever helps debug the issue
• Keep it terse: "getting user %s: %w" not "an error occurred while attempting to retrieve the user with ID %s from the database: %w"