1 Commits
Author SHA1 Message Date
clawbot 83df7a0f8d CODE_STYLEGUIDE_GO: propose naming rules (closes #174)
check / check (push) Successful in 43s
Adds a Naming section to the Go style guide: ten rules for package
names, thirteen for exported names as the caller reads them, and two
for local names. Each is one rule with its reason.

The sentence that banned `util` now points to the section, which bans
it along with `model`, `common`, `types`, `helpers`, `api` and the
like, and says what to name the package instead.

The guide's error example now uses an `Err` name, as the new rule on
error values asks.

This is a proposal. Nothing is renamed in any repo until sneak
approves or amends the rules.

Model: fable-5-2 (proposal); opus-5-5 (rework)
2026-11-16 06:05:19 +00:00
+48 -33
View File
@@ -221,7 +221,7 @@ last_modified: 2026-11-16
... ...
if err != nil { if err != nil {
SendErrorResponse(w, MSGenericError) SendErrorResponse(w, ErrBadRequest)
return return
} }
@@ -501,19 +501,27 @@ exported name, and reads them as one name: `http.Server`, `list.New`.
run together (`tabwriter`, never `tab_writer` or `tabWriter`), because that run together (`tabwriter`, never `tab_writer` or `tabWriter`), because that
is how the standard library spells every package name. is how the standard library spells every package name.
1. Never name a package `model`, `models`, `util`, `utils`, `common`, `misc`, 1. Never use a package name from the list below, or anything else that says
`helper`, `helpers`, `types`, `interfaces` or `api`, or anything else that nothing about what is in it, because every program has a data model, helpers
says nothing about what is in it: every program has a data model, helpers and types.
and types. Name the package for the one thing its code is about; when its - `model` and `models`
code is about several things, split it first (`stringset`, not `util`). - `util` and `utils`
- `common`
- `misc`
- `helper` and `helpers`
- `types`
- `interfaces`
- `api`
1. Split a package whose code is about several things, so that each part can be
named for what it provides (`stringset`, not `util`).
1. Spell a word out unless its short form is the one everybody already uses 1. Spell a word out unless its short form is the one everybody already uses
(`fmt`, `strconv`), because any other abbreviation has to be decoded. (`fmt`, `strconv`), because any other abbreviation has to be decoded.
1. Never give a package a name that callers want for a variable (`buf`, 1. Never give a package a name that callers want for a variable (`buf`) or that
`count`) or that a widely used standard package has (`log`, `http`, `url`), a widely used standard package has (`log`), because importers must rename
because every importer then has to rename one of the two. Use a longer name one of the two.
that says which one: `bufio`, `usercount`.
1. Give a package's directory the package's name, package `main` excepted, so 1. Give a package's directory the package's name, package `main` excepted, so
that the import path ends in the name the code uses. that the import path ends in the name the code uses.
@@ -522,44 +530,51 @@ exported name, and reads them as one name: `http.Server`, `list.New`.
plus `test` (`storetest`, never `testutil` or `testhelper`), because the plus `test` (`storetest`, never `testutil` or `testhelper`), because the
name then says whose tests it is for. name then says whose tests it is for.
1. Import a package under its own name. Give it a local name only when two 1. Import a package under its own name unless two imports share a name or its
imports have the same name or its own name breaks these rules, and use that own name breaks these rules, so that a reader knows it without checking the
local name in every file, so that one name always means one package. imports.
1. Give a renamed import the same local name in every file, so that one name
always means one package.
## Exported names ## Exported names
1. Never repeat the package name inside a longer exported name (`http.Server`, 1. Never repeat the package name inside a longer exported name (`http.Server`,
not `http.HTTPServer`; `yamlconfig.Parse`, not not `http.HTTPServer`; `yamlconfig.Parse`, not
`yamlconfig.ParseYAMLConfig`), because the caller has already written it. `yamlconfig.ParseYAMLConfig`), because the caller has already written it.
The type a package is named for may carry the same name on its own:
`list.List`, `time.Time`.
1. Use the same plain name in two packages when it fits both (`bufio.Reader`, 1. Use the same plain name in two packages when it fits both (`bufio.Reader`,
`csv.Reader`), because the package name already tells them apart. `csv.Reader`), because the package name already tells them apart.
1. Leave the receiver's type out of a method name, and the parameter and result 1. Leave the receiver's type out of a method name, and the parameter and result
types out of a function name (`(c *Config) WriteTo(w)`, not types out of a function name (`(c *Config) WriteTo(w)`, not
`WriteConfigTo`), because the signature already states them. Only when two `WriteConfigTo`), because the signature already states them.
functions differ in nothing but a type does the type go in, at the end:
`ParseInt`, `ParseInt64`.
1. Name a function that returns a value for the value and one that acts for the 1. Put a type at the end of a function's name when the type is the only
action (`JobName(key)`, `WriteDetail(w)`), so that a call reads as what it difference between two functions (`ParseInt`, `ParseInt64`), because Go
gives or what it does. needs a different name for each.
1. Use a noun for a function that returns something and a verb for one that
does something (`JobName(key)`, `WriteDetail(w)`), so that a call reads as
what it gives or does.
1. Never start a getter with `Get` (`Owner()`, not `GetOwner()`; the setter is 1. Never start a getter with `Get` (`Owner()`, not `GetOwner()`; the setter is
`SetOwner()`), because the capital letter already tells the method from the `SetOwner()`), because the capital letter already tells the method from the
field. A call that goes to a database or the network takes a verb that says field.
so (`Fetch`, `Load`), and `Get` stays only where it is the thing's own word,
as in an HTTP GET. 1. Begin the name of a database or network call with a verb that says so
(`Fetch`, `Load`), because the reader must know it can be slow or fail.
1. Name a one-method interface for its method plus `er` (`Reader`, 1. Name a one-method interface for its method plus `er` (`Reader`,
`Formatter`), because the name then says the one thing a value of it does. `Formatter`), because the name then says the one thing a value of it does.
1. Give a method that does what a well-known method does that method's name and 1. Use a well-known method's name and signature for a method that does the same
signature: `String()`, never `ToString()`. Give a method that does anything thing (`String()`, never `ToString()`), because readers and the standard
else another name, because readers and the standard interfaces rely on interfaces expect them.
`Read`, `Write`, `Close` and `String` meaning one thing.
1. Never reuse a well-known method name (`Read`, `Write`, `Close`, `String`)
for a method with another meaning or signature, because readers rely on each
name meaning one thing.
1. Write an initialism in one case throughout (`ServeHTTP`, `appID`, `URL` or 1. Write an initialism in one case throughout (`ServeHTTP`, `appID`, `URL` or
`url`; never `Url`, `Id` or `Http`), because that is how the standard `url`; never `Url`, `Id` or `Http`), because that is how the standard
@@ -575,13 +590,13 @@ exported name, and reads them as one name: `http.Server`, `list.New`.
## Local names ## Local names
1. Match a local name's length to the distance between its declaration and its 1. Match a local name's length to how far from its declaration it is used (`i`
last use (`i`, `r` and `db` across a few lines, a full word or two across a in a short loop), because a reader far from the declaration has only the
long function), because a reader far from the declaration has only the name. name.
1. Name a receiver with one or two letters, the same in every method of its 1. Name a receiver with one or two letters, the same in every method of its
type, never `this`, `self` or `me`, because it appears on nearly every line type, never `this`, `self` or `me`, because its role is plain from the
of those methods. method.
# Other Golang Tips and Best Practices (Optional) # Other Golang Tips and Best Practices (Optional)