🇺🇸English

Go Best Practices

Production patterns from Google, Uber, and the Go team. Updated for Go 1.25.

Sub-skills: skills/go-error-handling, skills/go-concurrency, skills/go-testing, skills/go-performance, skills/go-code-review, skills/go-linting, skills/go-project-layout, skills/go-security. Deep-dive references in references/.

Core Principles

Readable code prioritizes these attributes in order:

1. Clarity : purpose and rationale are obvious to the reader
2. Simplicity : accomplishes the goal in the simplest way
3. Concision : high signal to noise ratio
4. Maintainability : easy to modify correctly
5. Consistency : matches surrounding codebase

Error Handling

Full guide: skills/go-error-handling/SKILL.md | Reference: references/error-handling.md

• Return errors, never panic in production code

• Wrap with%w when callers need errors.Is/errors.As; use %v at boundaries

• Keep context succinct : "new store: %w" not "failed to create new store: %w"

• Handle errors once : don't log and return the same error

• Error strings : lowercase, no punctuation

• Indent error flow : handle errors first, keep happy path at minimal indentation

• Useerrors.Join (Go 1.20+) for multiple independent failures

Concurrency

Full guide: skills/go-concurrency/SKILL.md | Reference: references/concurrency.md

• Channel size : 0 (unbuffered) or 1; anything else needs justification

• Document goroutine lifetimes : when and how they exit

• Useerrgroup.Group over manual sync.WaitGroup for error-returning goroutines

• Prefer synchronous functions : let callers add concurrency

• Zero value mutexes : don't use pointers; don't embed in public structs

• Typed atomics (Go 1.19+): atomic.Int64, atomic.Bool, atomic.Pointer[T]

• sync.Map (Go 1.24+): significantly improved performance for disjoint key sets

Naming

• MixedCaps always : never underscores (MaxLength not MAX_LENGTH)
• Initialisms : consistent case (URL, ID, HTTP not Url, Id, Http)
• Short variables : scope determines length (i for loops, DefaultTimeout for globals)
• : 1-2 letter abbreviation, consistent across methods, never /

Pointer vs Value Receivers

Imports

import (
    "context"
    "fmt"

    "github.com/google/uuid"
    "golang.org/x/sync/errgroup"

    "yourcompany/internal/config"
)

• Three groups: stdlib, external, internal (separated by blank lines)
• Rename only to avoid collisions
• No dot imports except test files with circular deps
• Blank imports (import _ "pkg") only in main or tests

Module Management (Go 1.24+)

Track tool dependencies in go.mod with tool directives:

tool (
    golang.org/x/tools/cmd/stringer
    github.com/golangci/golangci-lint/cmd/golangci-lint
)



go get -tool golang.org/x/tools/cmd/stringer  # add
go tool stringer -type=Status                  # run
go get tool                                    # update all
go install tool                                # install to GOBIN

Structs

• Always use field names in initialization (positional breaks on changes)
• Omit zero value fields
• Don't embed types in public structs (exposes API unintentionally)
• Usevar for zero value structs: var user User

Slices and Maps

• Nil slices preferred : var t []string (use []string{} only for JSON [] encoding)
• Copy at boundaries : copy() or maps.Clone() to prevent mutation
• Preallocate : make([]T, 0, len(input)) when size is known
• Useslices and maps packages: slices.Sort, slices.Clone, ,

Generics (Go 1.18+)

• Use when writing identical code for different types

• Use cmp.Ordered or custom constraints for type safety

• Generic type aliases (Go 1.24+): type Set[T comparable] = map[T]struct{}

• Don't over-generalize : use concrete types or interfaces when they suffice

  func Filter[T any](s []T, pred func(T) bool) []T { result := make([]T, 0, len(s)) for _, v := range s { if pred(v) { result = append(result, v) } } return result }

Iterators (Go 1.23+)

Range over functions for custom iterators:

func Backward[T any](s []T) func(yield func(int, T) bool) {
    return func(yield func(int, T) bool) {
        for i := len(s) - 1; i >= 0; i-- {
            if !yield(i, s[i]) {
                return
            }
        }
    }
}

for i, v := range Backward(items) {
    fmt.Println(i, v)
}

String/bytes iterators (Go 1.24+): strings.Lines, strings.SplitSeq, strings.SplitAfterSeq

Structured Logging (Go 1.21+)

slog.Info("user created", "id", userID, "email", email)
slog.With("service", "auth").Info("starting")
handler := slog.NewJSONHandler(os.Stdout, &slog.HandlerOptions{Level: slog.LevelInfo})

• slog.DiscardHandler (Go 1.24+) for suppressing logs in tests
• Use consistent key names, group related fields with slog.Group

Performance

Full guide: skills/go-performance/SKILL.md | Reference: references/performance.md

• strconv over fmt: strconv.Itoa(n) not fmt.Sprintf("%d", n)
• Avoid repeated[]byte conversions: store once, reuse
• Preallocate map capacity : make(map[string]int, len(items))
• strings.Builder with Grow() for concatenation

Testing

Full guide: skills/go-testing/SKILL.md | Reference: references/testing.md

• Table-driven tests with t.Parallel() for subtests
• go-cmp over reflect.DeepEqual for clear diff output
• Useful failure messages : include input, got, want
• t.Fatal for setup failures
• Interfaces belong to consumers , not producers
• T.Context and T.Chdir (Go 1.24+)
• b.Loop() (Go 1.24+): cleaner benchmarks, no b.ResetTimer() needed

Resource Management (Go 1.24+)

• runtime.AddCleanup : multiple cleanups per object, no cycle leaks (replaces SetFinalizer)
• weak.Pointer[T] : weak references for caches, canonicalization, observers
• os.Root : scoped file access preventing path traversal attacks

Patterns

Full reference: references/patterns.md

• Functional options : WithTimeout(d), WithLogger(l) for configurable constructors
• Interface compliance : var _ http.Handler = (*Handler)(nil)
• Defer for cleanup : small overhead, worth the safety
• Graceful shutdown : signal handling + srv.Shutdown(ctx)
• Enums start at one : zero = invalid/unset
• Usetime.Duration: never raw ints for time
• Two-value type assertions : t, ok := i.(string) to avoid panics
• Context first : func Process(ctx context.Context, ...)

Common Gotchas

Full reference: references/gotchas.md

Linting

Full guide: skills/go-linting/SKILL.md

• Use golangci-lint as the standard linter aggregator
• Recommended linters : errcheck, govet, staticcheck, revive, gosimple, goimports, errorlint, bodyclose
• Add as a tool dependency (Go 1.24+): go get -tool github.com/golangci/golangci-lint/cmd/golangci-lint
• Run in CI : use golangci/golangci-lint-action for GitHub Actions
• Suppress sparingly : prefer fixing over //nolint comments

Project Layout

Full guide: skills/go-project-layout/SKILL.md

• cmd/ : one subdirectory per executable, keep main.go thin
• internal/ : private packages, enforced by the Go toolchain
• Avoidpkg/, src/, models/, utils/: name packages by purpose
• Flat is fine : small projects should not have deep directory trees
• Dockerfile : multi-stage build, CGO_ENABLED=0, distroless base image

Security

Full guide: skills/go-security/SKILL.md

• Parameterized SQL queries : never interpolate user input
• os.Root (Go 1.24+): scoped file access preventing path traversal
• Validate at boundaries : decode into typed structs, validate fields
• Never hardcode or log secrets : use Secret type with redacted String()
• Standard crypto only : crypto/rand for random bytes, bcrypt for passwords
• HTTP timeouts : always set ReadTimeout, WriteTimeout, IdleTimeout
• : scan dependencies for known vulnerabilities

Experimental (Go 1.25)

• encoding/json/v2 : enable with GOEXPERIMENT=jsonv2. Better performance, streaming, custom marshalers per call.

Documentation

• Comments are full sentences starting with the declared name
• Package comments: before package declaration, no blank line

References

1. Google Go Style Guide
2. Uber Go Style Guide
3. Effective Go
4. Go Code Review Comments
5. Go 1.23 Release Notes
6. Go 1.24 Release Notes
7. Go 1.25 Release Notes

Weekly Installs

333

Repository

saisudhir14/gol…nt-skill

GitHub Stars

6

First Seen

Jan 21, 2026

Security Audits

Gen Agent Trust HubPassSocketPassSnykPass

Installed on

gemini-cli280

opencode278

codex277

cursor265

github-copilot261

amp222