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.