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
+14 -19
View File
@@ -519,9 +519,9 @@ exported name, and reads them as one name: `http.Server`, `list.New`.
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. Lengthen a package name that callers want for a variable or that a widely 1. Never give a package a name that callers want for a variable (`buf`) or that
used standard package has (`bufio`, not `buf`; `auditlog`, not `log`), a widely used standard package has (`log`), because importers must rename
because importers must otherwise rename one of the two. one of the two.
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.
@@ -554,19 +554,16 @@ exported name, and reads them as one name: `http.Server`, `list.New`.
difference between two functions (`ParseInt`, `ParseInt64`), because Go difference between two functions (`ParseInt`, `ParseInt64`), because Go
needs a different name for each. needs a different name for each.
1. Use a noun for a function that only reports a value (`Owner()`, 1. Use a noun for a function that returns something and a verb for one that
`JobName(key)`), so that a call reads as the value it gives. does something (`JobName(key)`, `WriteDetail(w)`), so that a call reads as
what it gives or does.
1. Use a verb for a function that does work, even when it also returns a result
(`Parse`, `WriteDetail(w)`), so that a call reads as the work it 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.
1. Begin a function's name with `Fetch` or `Load` when it returns a value from 1. Begin the name of a database or network call with a verb that says so
a database or the network (`FetchOwner`, never `GetOwner` or `Owner`), (`Fetch`, `Load`), because the reader must know it can be slow or fail.
because the reader must know the call 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.
@@ -575,9 +572,9 @@ exported name, and reads them as one name: `http.Server`, `list.New`.
thing (`String()`, never `ToString()`), because readers and the standard thing (`String()`, never `ToString()`), because readers and the standard
interfaces expect them. interfaces expect them.
1. Give another name to a method that differs in meaning or signature from a 1. Never reuse a well-known method name (`Read`, `Write`, `Close`, `String`)
well-known method of the same name (`Read`, `Write`, `Close`, `String`), for a method with another meaning or signature, because readers rely on each
because readers rely on each name meaning one thing. 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
@@ -597,11 +594,9 @@ exported name, and reads them as one name: `http.Server`, `list.New`.
in a short loop), because a reader far from the declaration has only the in a short loop), because a reader far from the declaration has only the
name. name.
1. Name a receiver with one or two letters, never `this`, `self` or `me`, 1. Name a receiver with one or two letters, the same in every method of its
because its role is plain from the method. type, never `this`, `self` or `me`, because its role is plain from the
method.
1. Use the same receiver name in every method of a type, so that the name
always means the receiver.
# Other Golang Tips and Best Practices (Optional) # Other Golang Tips and Best Practices (Optional)