AGENT SKILL

golang-naming

Choose Go package, type, interface, method, and variable names for readable APIs. Preserve published identities and established repository conventions; renaming existing code also needs refactoring safeguards.

License 许可
MIT
最近更新
2026-11-14
Stars
★ 0
Forks
0

01 前言 Front Matter

name
golang-naming
paths
[ "**/*.go" ]
license
MIT
metadata
{ "author": "samber", "version": "1.2.1", "openclaw": { "emoji": "🏷", "install": [], "homepage": "https://github.com/samber/cc-skills-golang", "requires": { "bins": [ "go" ] } } }
description
Choose Go package, type, interface, method, and variable names for readable APIs. Preserve published identities and established repository conventions; renaming existing code also needs refactoring safeguards.
allowed-tools
Read Edit Write Glob Grep Bash(go build:*) Bash(go test:*) Bash(go vet:*) Bash(golangci-lint run:*) Bash(git status:*) Bash(git diff:*) Bash(git log:*) Bash(git show:*) Agent
compatibility
Designed for Claude Code, Codex or similar harness, and for projects using Golang.
user-invocable
true

02 资源文件 6

03 SKILL.md 正文

Community default. Company skill explicitly superseding samber/cc-skills-golang@golang-naming takes precedence.

Go Naming Conventions

"Clear is better than clever." — Go Proverbs

"Design the architecture, name the components, document the details." — Go Proverbs

To ignore a rule, add code comment.

Quick Reference

Element Convention Example
Package lowercase, single word, _test suffix OK for test files json, http, tabwriter, http_test
File lowercase, underscores OK user_handler.go
Exported name UpperCamelCase ReadAll, HTTPClient
Unexported lowerCamelCase parseToken, userCount
Interface method name + -er Reader, Closer, Stringer
Struct MixedCaps noun Request, FileHeader
Constant MixedCaps (not ALL_CAPS) MaxRetries, defaultTimeout
Receiver 1-2 letter abbreviation func (s *Server), func (b *Buffer)
Error variable Err prefix ErrNotFound, ErrTimeout
Error type Error suffix PathError, SyntaxError
Constructor New (single type) or NewTypeName (multi-type) ring.New, http.NewRequest
Boolean field house style: is/has/can prefix (stdlib often uses bare names: Closed, Valid) isReady, IsConnected()
Test function Test + function name TestParseToken
Acronym all caps or all lower URL, HTTPServer, xmlParser
Variant: context Context suffix (stdlib style); WithContext also seen QueryContext, ExecContext
Variant: in-place no stdlib convention; in-place usually default (slices.Sort), copying variant gets name slices.Sort (in place) vs slices.Sorted (returns new)
Variant: error Must prefix MustParse(), MustLoadConfig()
Option func With + field name WithPort(), WithLogger()
Enum (iota) type name prefix, zero-value = unknown StatusUnknown at 0, StatusReady
Named return descriptive, docs only (n int, err error)
Error string not capitalized (initialisms keep case), no punctuation "image: unknown format", "invalid ID"
Import alias short, only on collision mrand "math/rand", pb "app/proto"
Format func f suffix Errorf, Wrapf, Logf
Test table fields got/expected prefixes input string, expected int

MixedCaps

Capitalization controls visibility: uppercase is exported, lowercase unexported. All Go identifiers MUST use MixedCaps (or mixedCaps), NEVER underscores. Only exceptions: test function subcases (TestFoo_InvalidInput), generated code, OS/cgo interop.

// ✓ Good
MaxPacketSize
userCount
parseHTTPResponse

// ✗ Bad — these conventions conflict with Go's export mechanism and tooling expectations
MAX_PACKET_SIZE   // C/Python style
max_packet_size   // snake_case
kMaxBufferSize    // Hungarian notation

Avoid Stuttering

Name MUST NOT repeat what package name, type name, or surrounding context already says.

// Good — clean at the call site
http.Client       // not http.HTTPClient
json.Decoder      // not json.JSONDecoder
user.New()        // not user.NewUser()
config.Parse()    // not config.ParseConfig()

// In package sqldb:
type Connection struct{}  // not DBConnection — "db" is already in the package name

// Anti-stutter applies to ALL exported types, not just the primary struct:
// In package dbpool:
type Pool struct{}        // not DBPool
type Status struct{}      // not PoolStatus — callers write dbpool.Status
type Option func(*Pool)   // not PoolOption

Frequently Missed Conventions

Constructor naming: Package with single primary type: constructor is New(), not NewTypeName(). Use NewTypeName() only when package has multiple constructible types (like http.NewRequest, http.NewServeMux).

Boolean struct fields (house style, not an official Go rule): prefer is/has/can prefix on unexported boolean fields (isConnected, hasPermission). Exported getter keeps it: IsConnected() bool. Stdlib often uses bare names (Closed, Valid); follow codebase convention when it differs.

Error strings start lowercase and have no trailing punctuation: they often get concatenated with other context (fmt.Errorf("parsing token: %w", err)). Per Go Code Review Comments, proper nouns and initialisms keep case: "invalid message ID", "HTTP request failed". Sentinel errors should prefix package name: errors.New("apiclient: not found").

Enum zero values: Always put explicit Unknown/Invalid sentinel at iota position 0. var s Status silently becomes 0. If 0 is real state like StatusReady, code can treat unset status as deliberate choice.

Subtest names: t.Run() table case names should be fully lowercase descriptive phrases: "valid id", "empty input", not "valid ID" or "Valid Input".

Detailed Categories

Common Mistakes

Mistake Fix
GetName() getter Drop Get: user.Name() reads naturally. Boolean predicates keep Is/Has/Can: IsHealthy() bool not Healthy() bool
this or self receiver Methods get called often. Use 1-2 letter abbreviation (s for Server) to cut noise
util, helper packages Say nothing about content. Use specific names describing the abstraction
userSlice type-in-name Type leaks implementation detail. users says what it holds, not how
Inconsistent receiver names Confuses readers. Use one name across all methods of a type
Long names for short scopes Length should match scope. i fine for 3-line loop; userIndex is noise
Naming constants by value Values change, roles don't. DefaultPort survives port change, Port8080 doesn't
FetchCtx() context variant Spell it out. Stdlib uses Context suffix (QueryContext, DialContext); FetchWithContext() also common
Ambiguous mutate vs copy Document which one function does. Stdlib makes in-place default (slices.Sort) and names copying variant (slices.Sorted). In suffix is house convention, not Go's
parse() panicking on error MustParse() warns callers failure panics. Surprises belong in name
Mixing With*, Set*, Use* Stay consistent. With* is Go convention for functional options
Plural package names Go uses singular (net/url not net/urls). Keeps import paths consistent
Inconsistent concept names user/account/person for one concept forces readers to track synonyms. Pick one name

Applying these fixes means renaming existing identifiers. Use samber/cc-skills-golang@golang-gopls skill to do it safely. Its rename updates every call site across workspace and refuses renames that would break interface satisfaction, which grep/sed or manual Edit-based renames silently miss.

Enforce with Linters

Linters catch many naming issues automatically: revive, predeclared, misspell, errname. See samber/cc-skills-golang@golang-lint skill for configuration and usage.

Cross-References

  • → See samber/cc-skills-golang@golang-code-style skill for broader formatting and style
  • → See samber/cc-skills-golang@golang-structs-interfaces skill for interface naming depth and receiver design
  • → See samber/cc-skills-golang@golang-refactoring skill for safe renames at scale (gopls Rename/Inline, blast-radius mapping, staged PR workflow) once new names are chosen

04 同仓库更多 Skills

w0rxbend
w0rxbend/dot-agents

wiki-builder

Create and maintain a local Markdown research wiki (sources with provenance, compiled concept/source pages, index, maintenance log) driven by a per-wiki config. Use when the user wants to start a wiki or knowledge base, ingest sources into one, or query and update it; use wiki-page-writer for a single code deep-dive page.

★ 0
w0rxbend
w0rxbend/dot-agents

refactoring-guru

Diagnose a named code smell and apply the smallest behavior-preserving refactoring, with verification before and after and an explicit stop condition. Use for structural refactors (extract, move, consolidate, change ownership), not for feature or bug work; for readability cleanup of recent changes use code-simplification.

★ 0
w0rxbend
w0rxbend/dot-agents

legacy-seams

When changing untested legacy code, pin the observed results with characterization tests and open the smallest seam that substitutes only the blocking dependency, separate from any later logic change. Use when a clock, random source, I/O, global, or hidden constructor blocks a test or a safe edit. Use test-driven-development for a new behavior or a bug, refactoring-guru for one named structural refactor after the seam exists, and code-refactoring-tech-debt to choose which legacy to replace.

★ 0
w0rxbend
w0rxbend/dot-agents

idea-refine

Refine a raw idea into a one-page brief (problem statement, recommended direction, assumptions to validate, MVP scope, not-doing list) through divergent then convergent thinking. Use when an idea is still vague or you want options and a stress test before committing; use interview-me when the goal itself is unclear and spec-driven-development once the direction is chosen.

★ 0
w0rxbend
w0rxbend/dot-agents

code-review-and-quality

Review rubric and approval standard for any change before merge, including code written by you, another agent, or a human: five axes (correctness, readability, architecture, security, performance), change sizing, structural remedies, severity labels, and feedback technique. Use to judge whether a change is fit to merge; use code-review to run a PR or diff review end to end.

★ 0
w0rxbend
w0rxbend/dot-agents

code-perfection

Smell and style gate for code you write or change. Bans known code smells (long method, large class, primitive obsession, long parameter list, data clumps, duplicate code, dead code, feature envy, shotgun surgery, flag arguments, message chains) and enforces behavior-preserving structure. On Scala files, enforces worxbend style. Use while implementing, reviewing a diff for smells, or when a smell or style violation is suspected. Routine construction stays with code-complete. SOLID and DRY stay with clean-code-guard. One named structural refactor stays with refactoring-guru.

★ 0