1 Commits
Author SHA1 Message Date
clawbot d22642c2b5 CODE_STYLEGUIDE_GO: propose naming rules (closes #174)
check / check (push) Successful in 1m24s
Adds a Naming section to the Go style guide: eight rules for package
names, ten 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.

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

Model: fable-5-2
2026-11-16 05:21:35 +00:00
+33 -48
View File
@@ -221,7 +221,7 @@ last_modified: 2026-11-16
... ...
if err != nil { if err != nil {
SendErrorResponse(w, ErrBadRequest) SendErrorResponse(w, MSGenericError)
return return
} }
@@ -501,27 +501,19 @@ 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 use a package name from the list below, or anything else that says 1. Never name a package `model`, `models`, `util`, `utils`, `common`, `misc`,
nothing about what is in it, because every program has a data model, helpers `helper`, `helpers`, `types`, `interfaces` or `api`, or anything else that
and types. says nothing about what is in it: every program has a data model, helpers
- `model` and `models` and types. Name the package for the one thing its code is about; when its
- `util` and `utils` code is about several things, split it first (`stringset`, not `util`).
- `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`) or that 1. Never give a package a name that callers want for a variable (`buf`,
a widely used standard package has (`log`), because importers must rename `count`) or that a widely used standard package has (`log`, `http`, `url`),
one of the two. because every importer then has to rename one of the two. Use a longer name
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.
@@ -530,51 +522,44 @@ 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 unless two imports share a name or its 1. Import a package under its own name. Give it a local name only when two
own name breaks these rules, so that a reader knows it without checking the imports have the same name or its own name breaks these rules, and use that
imports. local name in every file, so that one name always means one package.
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. `WriteConfigTo`), because the signature already states them. Only when two
functions differ in nothing but a type does the type go in, at the end:
`ParseInt`, `ParseInt64`.
1. Put a type at the end of a function's name when the type is the only 1. Name a function that returns a value for the value and one that acts for the
difference between two functions (`ParseInt`, `ParseInt64`), because Go action (`JobName(key)`, `WriteDetail(w)`), so that a call reads as what it
needs a different name for each. gives or what it does.
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. field. A call that goes to a database or the network takes a verb that says
so (`Fetch`, `Load`), and `Get` stays only where it is the thing's own word,
1. Begin the name of a database or network call with a verb that says so as in an HTTP GET.
(`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. Use a well-known method's name and signature for a method that does the same 1. Give a method that does what a well-known method does that method's name and
thing (`String()`, never `ToString()`), because readers and the standard signature: `String()`, never `ToString()`. Give a method that does anything
interfaces expect them. else another name, because readers and the standard interfaces rely on
`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
@@ -590,13 +575,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 how far from its declaration it is used (`i` 1. Match a local name's length to the distance between its declaration and its
in a short loop), because a reader far from the declaration has only the last use (`i`, `r` and `db` across a few lines, a full word or two across a
name. long function), because a reader far from the declaration has only the 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 its role is plain from the type, never `this`, `self` or `me`, because it appears on nearly every line
method. of those methods.
# Other Golang Tips and Best Practices (Optional) # Other Golang Tips and Best Practices (Optional)