Golang Naming

Go Naming

Choose names that make the call site and surrounding code clear. Existing project vocabulary and public compatibility take precedence over generic style preferences.

Gather Context

Before proposing a name:

1. Read nearby declarations, callers, tests, documentation, serialized names, and generated-code boundaries.
2. Identify whether the symbol is exported, part of a public module, referenced through reflection or templates, or tied to a wire/database schema.
3. Search for the domain concept across the repository. Reuse established terminology unless inconsistency is itself the problem.
4. Compare names at their call sites, including the package qualifier. Avoid judging an identifier in isolation.

Decision Principles

• Prefer the shortest name that stays unambiguous in its scope.
• Let package, receiver, and type context carry information; avoid repeating it in every identifier.
• Use Go's capitalization rules and familiar initialism spelling, but preserve a project's stable public convention when changing it would be disruptive.
• Name functions for what callers observe, including meaningful cost, mutation, blocking, or panic behavior when those would otherwise surprise callers.
• Use one domain term for one concept. Do not alternate synonyms without a real distinction.
• Avoid implementation details in a name when the abstraction can change independently.
• Treat zero values, error identity, and generated/serialized names as API design concerns rather than cosmetic naming.

Review by Category

• For packages, files, and import aliases, read references/packages-files.md.
• For variables, parameters, receivers, booleans, and initialisms, read references/identifiers.md.
• For functions, methods, constructors, getters, and options, read references/functions-methods.md.
• For types, interfaces, constants, enum-like values, and errors, read references/types-errors.md.
• For test and benchmark names, read references/testing.md.

Load only the references relevant to the naming decision.

Applying a Rename

Prefer a language-aware rename operation when available. Before editing, map references across the workspace and check:

• interface satisfaction and method expressions;
• exported API users and compatibility promises;
• struct tags, JSON/YAML/database names, environment variables, flags, metrics, logs, templates, and reflection;
• generated files and generation inputs;
• examples, tests, documentation, and configuration.

Do not silently rename an external contract together with the Go identifier. Preserve the external name unless changing that contract is explicitly in scope.

After the rename, format changed Go files and run the repository's build, test, vet, and generation checks. Inspect the diff for unrelated textual replacements.

Deliverable

When presenting alternatives, show representative call sites and explain the distinction each name communicates. If no option is clearly better, preserve the established name rather than creating churn.