go-naming

Files (2)

• SKILL.md
• examples.md · references/

SKILL.md (first lines)

# Go Naming

In Go the package name is part of every call site, capitalization decides
visibility, and short names are the norm. A good name reads well *where it
is used*, not where it is declared.

> Community default. A project skill or agent-config rule that explicitly
> supersedes `go-naming` takes precedence over this one.

Detailed reference material, loaded on demand:

- `references/examples.md` — before/after renames for every rule below,
  including the initialism and stuttering edge cases.

Read a reference file only when the summary below is not enough.

## 1. Quick Reference

| Element | Convention | Example |
|---|---|---|
| Package | short, lowercase, one word, singular | `order`, `httpsign`, `postgres` |
| File | lowercase, `_` allowed, named after its main type or concern | `order_service.go`, `order_service_test.go` |
| Exported identifier | `MixedCaps` | `ParseToken`, `MaxRetries` |
| Unexported identifier | `mixedCaps` | `parseToken`, `maxRetries` |
| Initialism | all one case | `URL`, `userID`, `ServeHTTP`, `xmlParser` |
| Getter / setter | `Owner()` / `SetOwner()` | never `GetOwner()` |
| Constructor | `New` for the package's main type, `NewThing` otherwise | `ring.New`, `http.NewRequest` |
| Panicking variant | `Must` prefix | `template.Must`, `regexp.MustCompile` |
| Functional option | `With` + setting | `WithTimeout`, `WithLogger` |
| One-method interface | method + `-er` | `Reader`, `Notifier` |
| Receiver | 1-2 letters, same on every method | `func (s *Server)` |
| Sentinel error | `Err` prefix (`err` unexported) | `ErrNotFound`, `errClosed` |
| Error type | `Error` suffix | `ValidationError` |
| Enum constant | type name prefix, zero = unknown | `StatusUnknown`, `StatusActive` |
| Test | `Test` + function, `Test` + type `_` method | `TestParse`, `TestCache_Get` |

## 2. Packages

- Short, lowercase, single word: no underscores, no `mixedCaps`, no plural
  (`order`, not `orders`).
- Name it after what it *provides*: `retry`, `httpsign`, `postgres`. Never
  `util`, `common`, `helpers`, `misc`, `base`, `models`, `types` — they
  say nothing and collect everything.
- The directory name and the package name match.
- Avoid names callers want for their variables (`url`, `user`, `buf`) when
  the package is imported widely; a call site with `u := user.New()` reads
  better than shadowing the package.

## 3. Don't Stutter

The package name is always present at the call site, so don't repeat it:

```go
// ✅ Good — reads once
http.Client       order.Service     user.New()     config.Load()

// ❌ Bad — says it twice
http.HTTPClient   order.OrderService user.NewUser() config.LoadConfig()
```

The rule covers every exported name in the package, not just the main
type: in package `dbpool`, `Pool`, `Status` and `Option` — not `DBPool`,
`PoolStatus`, `PoolOption`.

## 4. MixedCaps, Initialisms and Constants

- Every identifier is `MixedCaps` or `mixedCaps`. Underscores appear only
  in test names (`TestCache_Get`), generated code, and cgo.
- An initialism keeps one case throughout: `URL`, `ID`, `HTTP`, `JSON`,
  `API` — `userID`, `parseURL`, `ServeHTTP`, `HTTPServer`, `xmlHTTPRequest`.
  Never `UserId`, `ParseUrl`, `HttpServer`.
- Constants are `MixedCaps` like everything else: `MaxRetries`, not
  `MAX_RETRIES` — case already means "exported" in Go.
- Name constants for their role, not their value: `DefaultPort`, not
  `Port8080`.
- Do not shadow predeclared identifiers: `len`, `cap`, `new`, `make`,
  `close`, `copy`, `error`, `string`, `min`, `max`.

## 5. Functions and Methods

- Getters drop `Get`: `u.Name()`, and the setter is `u.SetName()`.
  `Is`/`Has`/`Can` stay on boolean predicates: `IsActive()`.
- Constructors: `New` when the package has one main type, `NewThing`
  otherwise. A constructor that panics on bad input is `MustThing`.
- Canonical names carry a contract. Call a method `Read`, `Write`,
  `Close`, `Flush`, `String`, `Error` or `ServeHTTP` only if it has the
  standard signature and meaning — and if it does, use that name
  (`String()`, never `ToString()`).
- Name for what the caller gets, not how it is computed: `Users()`, not
  `QueryAndBuildUserList()`.
- Format-string variants end in `f`: `Errorf`, `Logf`.

## 6. Variables and Receivers

- Name length grows with scope: `i`, `n`, `err`, `ctx`, `buf` inside a few
  lines; `retryTimeout`, `pendingOrders` across a function; full words at
  package level.
- Don't put the type in the name (`userSlice` → `users`, `nameStr` →
  `name`), and don't repeat context the reader already has (`order.ID`
  inside `type Order`, not `order.OrderID`).
- Receivers are one or two letters from the type (`s *Server`,
  `rw *responseWriter`), the same on every method of the type — never
  `this` or `self`.
- Unexported package-level variables may take a `_` prefix
  (`_defaultTimeout`) to keep them distinct from locals — the Uber style
  convention. Follow whichever the codebase already uses.
- Boolean names read as a question: `isReady`, `hasChildren`, `canRetry`.

## 7. Types and Interfaces

- Types are nouns: `Request`, `FileHeader`, `RetryPolicy`.
- A one-method interface is the method plus `-er`: `Reader`, `Notifier`,
  `Validator`. Never an `I` prefix or `Interface` suffix.
- Name an interface after the behavior the consumer needs, in the
  consumer's package (`orderStore` in the service), not after the
  implementation it happens to have.

## 8. Errors

From eduardo-sl/go-agent-skills, MIT.

More from eduardo-sl/go-agent-skills