golang-rules

Go Rules

These rules come from app/rules/golang/ in ai-toolkit. They cover the project's standards for coding style, frameworks, patterns, security, and testing in Go. Apply them when writing or reviewing Go code.

Go Coding Style

Naming

• MixedCaps/mixedCaps only. No underscores in Go names (except test functions).
• Exported: PascalCase. Unexported: camelCase. Acronyms: HTTPClient, userID.
• Short variable names in small scopes: i, r, w, ctx, err.
• Descriptive names in larger scopes: userRepository, requestTimeout.
• Package names: short, lowercase, singular (auth, user, not utils, helpers).

Packages

• One package per directory. Package name = directory name.
• Avoid util, common, helpers packages. Name by what it provides.
• Keep package APIs small. Export only what consumers need.
• Use internal/ directory for packages not meant for external consumption.

Functions

• Accept interfaces, return structs.
• First parameter ctx context.Context if the function does I/O or may be cancelled.
• Return (result, error) tuple. Error is always last return value.
• Use named return values only for documentation, not for naked returns.
• Keep functions short. If >40 lines, consider splitting.

Error Handling

• Always check errors. Never use _ to discard errors silently.
• Wrap errors with context: fmt.Errorf("fetching user %s: %w", id, err).
• Use sentinel errors (var ErrNotFound = errors.New(...)) for expected conditions.
• Use errors.Is() and errors.As() for error checking, not type assertions.

Formatting

• Use gofmt / goimports. No formatting debates in Go.
• Use golangci-lint with a .golangci.yml config in CI.
• Use go vet as minimum static analysis.

Struct Design

• Use struct embedding for composition, not inheritance.
• Prefer value receivers for small structs, pointer receivers for large or mutable.
• Be consistent: all methods on a type use the same receiver type.
• Use struct literals with field names: User{Name: "Ada", Age: 30}.