From 83df7a0f8d80196048f2deab7e36840f06c05938 Mon Sep 17 00:00:00 2001 From: clawbot <35+clawbot@noreply.example.org> Date: Mon, 16 Nov 2026 05:21:35 +0000 Subject: [PATCH] CODE_STYLEGUIDE_GO: propose naming rules (closes #174) 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) --- prompts/CODE_STYLEGUIDE_GO.md | 117 +++++++++++++++++++++++++++++++++- 1 file changed, 114 insertions(+), 3 deletions(-) diff --git a/prompts/CODE_STYLEGUIDE_GO.md b/prompts/CODE_STYLEGUIDE_GO.md index 82e5c82..21b9ff2 100644 --- a/prompts/CODE_STYLEGUIDE_GO.md +++ b/prompts/CODE_STYLEGUIDE_GO.md @@ -1,6 +1,6 @@ --- 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`. @@ -176,7 +176,7 @@ last_modified: 2026-11-07 them a bit long. 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 `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 { - SendErrorResponse(w, MSGenericError) + SendErrorResponse(w, ErrBadRequest) return } @@ -487,6 +487,117 @@ last_modified: 2026-11-07 releasable". "Releasable" in this context means that it builds and functions 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) 1. For any internet-facing http server, set appropriate timeouts and limits to -- 2.54.0