CODE_STYLEGUIDE_GO: propose naming rules (closes #174)
check / check (push) Waiting to run

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)
This commit is contained in:
clawbot committed 2026-11-16 06:05:19 +00:00
1 parent 69d38ba6de
commit 83df7a0f8d
1 file changed
+114 -3
+114 -3
View File
@@ -1,6 +1,6 @@
--- ---
title: Code Styleguide — Go title: Code Styleguide — Go
last_modified: 2026-11-07 last_modified: 2026-11-16
--- ---
1. Format Go code with `gofmt` and then `golines -m 77`, through `make fmt`. 1. Format Go code with `gofmt` and then `golines -m 77`, through `make fmt`.
@@ -176,7 +176,7 @@ last_modified: 2026-11-07
them a bit long. them a bit long.
1. Use descriptive names for modules and filenames. Avoid generic names like 1. Use descriptive names for modules and filenames. Avoid generic names like
`server`. `util` is banned. `server`. The rules for package names are under Naming, below.
1. Constructors **must** take a `Params` struct (or `ThingParams` when 1. Constructors **must** take a `Params` struct (or `ThingParams` when
`NewThing()` is used), even for a single argument. Named fields in a Params `NewThing()` is used), even for a single argument. Named fields in a Params
@@ -221,7 +221,7 @@ last_modified: 2026-11-07
... ...
if err != nil { if err != nil {
SendErrorResponse(w, MSGenericError) SendErrorResponse(w, ErrBadRequest)
return return
} }
@@ -487,6 +487,117 @@ last_modified: 2026-11-07
releasable". "Releasable" in this context means that it builds and functions releasable". "Releasable" in this context means that it builds and functions
as expected, and that all tests and linting passes. as expected, and that all tests and linting passes.
# Naming
Judge a name where it is read. A caller writes the package name, a dot and the
exported name, and reads them as one name: `http.Server`, `list.New`.
## Package names
1. Name a package for what it provides (`time`, `list`, `http`), because the
caller writes that name in front of everything the package exports.
1. Write a package name in lowercase letters and digits only, with its words
run together (`tabwriter`, never `tab_writer` or `tabWriter`), because that
is how the standard library spells every package name.
1. Never use a package name from the list below, or anything else that says
nothing about what is in it, because every program has a data model, helpers
and types.
- `model` and `models`
- `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
(`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
a widely used standard package has (`log`), because importers must rename
one of the two.
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.
1. Name a package that supports the tests of one package after that package
plus `test` (`storetest`, never `testutil` or `testhelper`), because the
name then says whose tests it is for.
1. Import a package under its own name unless two imports share a name or its
own name breaks these rules, so that a reader knows it without checking the
imports.
1. Give a renamed import the same local name in every file, so that one name
always means one package.
## Exported names
1. Never repeat the package name inside a longer exported name (`http.Server`,
not `http.HTTPServer`; `yamlconfig.Parse`, not
`yamlconfig.ParseYAMLConfig`), because the caller has already written it.
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.
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
`WriteConfigTo`), because the signature already states them.
1. Put a type at the end of a function's name when the type is the only
difference between two functions (`ParseInt`, `ParseInt64`), because Go
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
`SetOwner()`), because the capital letter already tells the method from the
field.
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`,
`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
thing (`String()`, never `ToString()`), because readers and the standard
interfaces expect them.
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
`url`; never `Url`, `Id` or `Http`), because that is how the standard
library spells them.
1. Write a constant in MixedCaps like every other name (`MaxPacketSize`, never
`MAX_PACKET_SIZE`), because an all-capitals name is exported whether or not
that was meant.
1. Name an error value `Err` plus what went wrong (`ErrNotFound`) and an error
type for what went wrong plus `Error` (`NotFoundError`), because callers
know a package's errors by those two forms.
## Local names
1. Match a local name's length to how far from its declaration it is used (`i`
in a short loop), 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
type, never `this`, `self` or `me`, because its role is plain from the
method.
# Other Golang Tips and Best Practices (Optional) # Other Golang Tips and Best Practices (Optional)
1. For any internet-facing http server, set appropriate timeouts and limits to 1. For any internet-facing http server, set appropriate timeouts and limits to