/golang-naming

name: golang-naming
description: "Go (Golang) naming conventions — covers packages, constructors, structs, interfaces, constants, enums, errors, booleans, receivers, getters/setters, functional options, acronyms, test functions, and subtest names. Use this skill when writing new Go code, reviewing or refactoring, choosing between naming alternatives (New vs NewTypeName, isConnected vs connected, ErrNotFound vs NotFoundError, StatusReady vs StatusUnknown at iota 0), debating Go package names (utils/helpers anti-patterns), or asking about Go naming best practices. Also trigger when the user mentions MixedCaps vs snake_case, ALL_CAPS constants, Get-prefix on getters, or error string casing. Do NOT use for general Go implementation questions that don't involve naming decisions."
user-invocable: true
license: MIT
compatibility: Designed for Claude Code or similar AI coding agents, and for projects using Golang.
metadata:
  author: samber
  version: "1.1.2"
  openclaw:
    emoji: "🏷"
    homepage: https://github.com/samber/cc-skills-golang
    requires:
      bins:
        - go
    install: []
allowed-tools: Read Edit Write Glob Grep Bash(go:*) Bash(golangci-lint:*) Bash(git:*) Agent

> **Community default.** A company skill that explicitly supersedes `samber/cc-skills-golang@golang-naming` skill takes precedence.

Go Naming Conventions

Go favors short, readable names. Capitalization controls visibility — uppercase is exported, lowercase is unexported. All identifiers MUST use MixedCaps, NEVER underscores.

> "Clear is better than clever." — Go Proverbs > > "Design the architecture, name the components, document the details." — Go Proverbs

To ignore a rule, just add a comment to the code.

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 | `is`, `has`, `can` prefix on **fields** and methods | `isReady`, `IsConnected()` | | Test function | `Test` + function name | `TestParseToken` | | Acronym | all caps or all lower | `URL`, `HTTPServer`, `xmlParser` | | Variant: context | `WithContext` suffix | `FetchWithContext`, `QueryContext` | | Variant: in-place | `In` suffix | `SortIn()`, `ReverseIn()` | | 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, for docs only | `(n int, err error)` | | Error string | lowercase (incl. acronyms), 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

All Go identifiers MUST use `MixedCaps` (or `mixedCaps`). NEVER use underscores in identifiers — the only exceptions are test function subcases (`TestFoo_InvalidInput`), generated code, and OS/cgo interop. This is load-bearing, not cosmetic — Go's export mechanism relies on capitalization, and tooling assumes MixedCaps throughout.

// ✓ 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

Go call sites always include the package name, so repeating it in the identifier wastes the reader's time — `http.HTTPClient` forces parsing "HTTP" twice. A name MUST NOT repeat information already present in the package name, type name, or surrounding context.

// 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

These conventions are correct but non-obvious — they are the most common source of naming mistakes:

**Constructor naming:** When a package exports a single primary type, the constructor is `New()`, not `NewTypeName()`. This avoids stuttering — callers write `apiclient.New()` not `apiclient.NewClient()`. Use `NewTypeName()` only when a package has multiple constructible types (like `http.NewRequest`, `http.NewServeMux`).

**Boolean struct fields:** Unexported boolean fields MUST use `is`/`has`/`can` prefix — `isConnected`, `hasPermission`, not bare `connected` or `permission`. The exported getter keeps the prefix: `IsConnected() bool`. This reads naturally as a question and distinguishes booleans from other types.

**Error strings are fully lowercase — including acronyms.** Write `"invalid message id"` not `"invalid message ID"`, because error strings are often concatenated wi