# Golang Code Style

> Write or review readable, idiomatic Go code with attention to control flow, declarations, comments, file organization, and API clarity. Use for focused style work or project coding conventions; use dedicated naming, lint, documentation, or architecture guidance when those are the main task.

- Skill: `reagin/golang-code-style` (Agent Skill)
- Install (CLI): `npx skillmds@latest add reagin/golang-code-style`
- Raw SKILL.md: https://api.skillmd.com/api/skills/reagin/golang-code-style/raw
- Safety review: pending
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: Docs & Writing
- License: MIT
- Author: reagin (https://skillmd.com/u/reagin)
- Updated: 2026-09-17
- Page: https://skillmd.com/skills/reagin/golang-code-style

---


# Go Code Style

Make code easier to understand without turning preferences into universal rules. Preserve behavior, public APIs, and repository conventions unless the user explicitly asks to change them.

## Establish the local style

Before editing:

1. Read repository instructions, `go.mod`, formatter and linter configuration, and nearby code.
2. Identify whether the task is implementation, focused review, or project-wide policy design, and keep the change at that scale.
3. Use `gofmt` as the formatting baseline. Use stricter formatters only when the project already configures them.
4. Prefer established local conventions when several idiomatic forms are equally clear.

## Clarity heuristics

Apply these with judgment:

- Handle exceptional paths early when that makes the main flow flatter. Keep an `else` when it expresses a real two-way decision more clearly.
- Give intermediate values names when they reveal domain meaning or make a condition auditable. Do not extract trivial expressions merely to satisfy an operand count.
- Keep a value's scope narrow, including `if` initializers when the value is used only by that branch.
- Split functions when the extracted operation has a coherent responsibility, invariant, or test boundary—not because of an arbitrary line threshold.
- Group parameters into a request or options type when they form a stable concept or evolution point. A long signature alone is not sufficient reason.
- Use `switch` when it clarifies one discriminant or a set of mutually exclusive cases; do not replace a short, natural `if` mechanically.
- Prefer explicit initialization when nil and empty have observably different semantics, such as a JSON contract. Otherwise preserve useful zero values.
- Use keyed fields for literals of exported or evolving structs. Positional literals can remain appropriate for small, local, intentionally tuple-like types.
- Pass values or pointers according to mutation, identity, optionality, copying cost, and existing API contracts. Benchmark copy concerns on hot paths rather than relying on size folklore.

## Comments and organization

Comments should explain constraints, invariants, compatibility decisions, or why an apparently simpler approach is wrong. Remove comments that only narrate syntax. Preserve required exported documentation and generated-code conventions.

Within a file, keep related declarations close enough to navigate naturally. Avoid reorganizing an entire package during a focused change unless the current layout blocks the requested work.

Keep public surface area intentional. Do not export, unexport, rename, or move a symbol without checking callers, interface satisfaction, generated code, serialization contracts, and compatibility requirements.

## Review standard

Report only changes that materially improve comprehension or reduce maintenance risk. Separate:

- correctness or behavioral risks;
- repository-enforced conventions;
- optional readability suggestions.

For each non-obvious recommendation, explain the concrete reading or maintenance problem it solves. Do not require explanatory comments solely because code chooses a reasonable alternative style.

When changes are requested, format and run the repository's existing focused checks. Keep formatter, linter, dependency, and project-wide policy changes separate from a focused style edit.