Golang Code Style

1---2name: golang-code-style3description: "Golang code style, formatting and conventions. Use when writing code, reviewing style, configuring linters, writing comments, or establishing project standards."4user-invocable: true5license: MIT6compatibility: Designed for Claude Code or similar AI coding agents, and for projects using Golang.7metadata:8  author: samber9  version: "1.1.1"10  openclaw:11    emoji: "🎨"12    homepage: https://github.com/samber/cc-skills-golang13    requires:14      bins:15        - go16    install: []17allowed-tools: Read Edit Write Glob Grep Bash(go:*) Bash(golangci-lint:*) Bash(git:*) Agent18---19 20> **Community default.** A company skill that explicitly supersedes `samber/cc-skills-golang@golang-code-style` skill takes precedence.21 22# Go Code Style23 24Style rules that require human judgment — linters handle formatting, this skill handles clarity. For naming see `samber/cc-skills-golang@golang-naming` skill; for design patterns see `samber/cc-skills-golang@golang-design-patterns` skill; for struct/interface design see `samber/cc-skills-golang@golang-structs-interfaces` skill.25 26> "Clear is better than clever." — Go Proverbs27 28When ignoring a rule, add a comment to the code.29 30## Line Length & Breaking31 32No rigid line limit, but lines beyond ~120 characters MUST be broken. Break at **semantic boundaries**, not arbitrary column counts. Function calls with 4+ arguments MUST use one argument per line — even when the prompt asks for single-line code:33 34```go35// Good — each argument on its own line, closing paren separate36mux.HandleFunc("/api/users", func(w http.ResponseWriter, r *http.Request) {37    handleUsers(38        w,39        r,40        serviceName,41        cfg,42        logger,43        authMiddleware,44    )45})46```47 48When a function signature is too long, the real fix is often **fewer parameters** (use an options struct) rather than better line wrapping. For multi-line signatures, put each parameter on its own line.49 50## Variable Declarations51 52SHOULD use `:=` for non-zero values, `var` for zero-value initialization. The form signals intent: `var` means "this starts at zero."53 54```go55var count int              // zero value, set later56name := "default"          // non-zero, := is appropriate57var buf bytes.Buffer       // zero value is ready to use58```59 60### Slice & Map Initialization61 62Slices and maps MUST be initialized explicitly, never nil. Nil maps panic on write; nil slices serialize to `null` in JSON (vs `[]` for empty slices), surprising API consumers.63 64```go65users := []User{}                       // always initialized66m := map[string]int{}                   // always initialized67users := make([]User, 0, len(ids))      // preallocate when capacity is known68m := make(map[string]int, len(items))   // preallocate when size is known69```70 71Do not preallocate speculatively — `make([]T, 0, 1000)` wastes memory when the common case is 10 items.72 73### Composite Literals74 75Composite literals MUST use field names — positional fields break when the type adds or reorders fields:76 77```go78srv := &http.Server{79    Addr:         ":8080",80    ReadTimeout:  5 * time.Second,81    WriteTimeout: 10 * time.Second,82}83```84 85## Control Flow86 87### Reduce Nesting88 89Errors and edge cases MUST be handled first (early return). Keep the happy path at minimal indentation:90 91```go92func process(data []byte) (*Result, error) {93    if len(data) == 0 {94        return nil, errors.New("empty data")95    }96 97    parsed, err := parse(data)98    if err != nil {99        return nil, fmt.Errorf("parsing: %w", err)100    }101 102    return transform(parsed), nil103}104```105 106### Eliminate Unnecessary `else`107 108When the `if` body ends with `return`/`break`/`continue`, the `else` MUST be dropped. Use default-then-override for simple assignments — assign a default, then override with independent conditions or a `switch`:109 110```go111// Good — default-then-override with switch (cleanest for mutually exclusive overrides)112level := slog.LevelInfo113switch {114case debug:115    level = slog.LevelDebug116case verbose:117    level = slog.LevelWarn118}119 120// Bad — else-if chain hides that there's a default121if debug {122    level = slog.LevelDebug123} else if verbose {124    level = slog.LevelWarn125} else {126    level = slog.LevelInfo127}128```129 130### Complex Conditions & Init Scope131 132When an `if` condition has 3+ operands, MUST extract into named booleans — a wall of `||` is unreadable and hides business logic. Keep expensive checks inline for short-circuit benefit. [Details](./references/details.md)133 134```go135// Good — named booleans make intent clear136isAdmin := user.Role == RoleAdmin137isOwner := resource.OwnerID == user.ID138isPublicVerified := resource.IsPublic && user.IsVerified139if isAdmin || isOwner || isPublicVerified || permissions.Contains(PermOverride) {140    allow()141}142```143 144Scope variables to `if` blocks when only needed for the check:145 146```go147if err := validate(input); err != nil {148    return err149}150```151 152### Switch Over If-Else Chains153 154When comparing the same variable multiple times, prefer `switch`:155 156```go157switch status {158case StatusActive:159    activate()160case StatusInactive:161    deactivate()162default:163    panic(fmt.Sprintf("unexpected status: %d", status))164}165```166 167## Function Design168 169- Functions SHOULD be **short and focused** — one function, one job.170- Functions SHOULD have **≤4 parameters**. Beyond that, use an options struct (see `samber/cc-skills-golang@golang-design-patterns` skill).171- **Parameter order**: `context.Context` first, then inputs, then output destinations.172- Naked returns help in very short functions (1-3 lines) where return values are obvious, but become confusing when readers must scroll to find what's returned — name returns explicitly in longer functions.173 174```go175func FetchUser(ctx context.Context, id string) (*User, error)176func SendEmail(ctx context.Context, msg EmailMessage) error  // grouped into struct177```178 179### Prefer `range` for Iteration180 181SHOULD use `range` over index-based loops. Use `range n` (Go 1.22+) for simple counting.182 183```go184for _, user := range users {185    process(user)186}187```188 189## Value vs Pointer Arguments190 191Pass small types (`string`, `int`, `bool`, `time.Time`) by value. Use pointers when mutating, for large structs (~128+ bytes), or when nil is meaningful. [Details](./references/details.md)192 193## Code Organization Within Files194 195- **Group related declarations**: type, constructor, methods together196- **Order**: package doc, imports, constants, types, constructors, methods, helpers197- **One primary type per file** when it has significant methods198- **Blank imports** (`_ "pkg"`) register side effects (init functions). Restricting them to `main` and test packages makes side effects visible at the application root, not hidden in library code199- **Dot imports** pollute the namespace and make it impossible to tell where a name comes from — never use in library code200- **Unexport aggressively** — you can always export later; unexporting is a breaking change201 202## String Handling203 204Use `strconv` for simple conversions (faster), `fmt.Sprintf` for complex formatting. Use `%q` in error messages to make string boundaries visible. Use `strings.Builder` for loops, `+` for simple concatenation.205 206## Type Conversions207 208Prefer explicit, narrow conversions. Use generics over `any` when a concrete type will do:209 210```go211func Contains[T comparable](slice []T, target T) bool  // not []any212```213 214## Philosophy215 216- **"A little copying is better than a little dependency"**217- **Use `slices` and `maps` standard packages**; for filter/group-by/chunk, use `github.com/samber/lo`218- **"Reflection is never clear"** — avoid `reflect` unless necessary219- **Don't abstract prematurely** — extract when the pattern is stable220- **Minimize public surface** — every exported name is a commitment221 222## Parallelizing Code Style Reviews223 224When reviewing code style across a large codebase, use up to 5 parallel sub-agents (via the Agent tool), each targeting an independent style concern (e.g. control flow, function design, variable declarations, string handling, code organization).225 226## Enforce with Linters227 228Many rules are enforced automatically: `gofmt`, `gofumpt`, `goimports`, `gocritic`, `revive`, `wsl_v5`. → See the `samber/cc-skills-golang@golang-linter` skill.229 230## Cross-References231 232- → See the `samber/cc-skills-golang@golang-naming` skill for identifier naming conventions233- → See the `samber/cc-skills-golang@golang-structs-interfaces` skill for pointer vs value receivers, interface design234- → See the `samber/cc-skills-golang@golang-design-patterns` skill for functional options, builders, constructors235- → See the `samber/cc-skills-golang@golang-linter` skill for automated formatting enforcement