Proposal for the naming-rules issue, #174: a Naming section in prompts/CODE_STYLEGUIDE_GO.md, twenty-seven rules, each with its reason. Nothing is renamed in any repo until sneak approves or amends them.
Where each rule comes from:
Package names
Named for what the package provides; lowercase with words run together; only familiar abbreviations: Effective Go and the Go blog post "Package names".
No model, util, common, types, helpers, api and the like, and splitting such packages: sneak on model; "Package names"; Go Code Review Comments; the Go Style Guide, which also lists model.
No name a caller wants for a variable or a standard package has: "Package names"; the Go Style Guide.
Directory named as the package: Effective Go.
Test-support packages named like storetest; import names: the Go Style Guide.
Exported names
No package name repeated; the same plain name in two packages: Effective Go; "Package names"; Code Review Comments.
Types in a name; noun or verb; Fetch for a getter that reads from a database or the network: the Go Style Guide.
No Get; er interfaces; well-known method names: Effective Go.
Initialisms; MixedCaps constants: Code Review Comments; the Go Style Guide.
ErrNotFound and NotFoundError: the Go wiki page "Errors", which is not one of the four sources.
Local names (length by scope; receivers): Code Review Comments; the Go Style Guide.
The first comment lists the renames and the judgement calls.
Model: fable-5-2 (proposal); opus-5-5 (rework)
Proposal for the naming-rules issue, https://git.eeqj.de/sneak/prompts/issues/174: a Naming section in `prompts/CODE_STYLEGUIDE_GO.md`, twenty-seven rules, each with its reason. Nothing is renamed in any repo until sneak approves or amends them.
Where each rule comes from:
- Package names
- Named for what the package provides; lowercase with words run together; only familiar abbreviations: Effective Go and the Go blog post "Package names".
- No `model`, `util`, `common`, `types`, `helpers`, `api` and the like, and splitting such packages: sneak on `model`; "Package names"; Go Code Review Comments; the Go Style Guide, which also lists `model`.
- No name a caller wants for a variable or a standard package has: "Package names"; the Go Style Guide.
- Directory named as the package: Effective Go.
- Test-support packages named like `storetest`; import names: the Go Style Guide.
- Exported names
- No package name repeated; the same plain name in two packages: Effective Go; "Package names"; Code Review Comments.
- Types in a name; noun or verb; `Fetch` for a getter that reads from a database or the network: the Go Style Guide.
- No `Get`; `er` interfaces; well-known method names: Effective Go.
- Initialisms; MixedCaps constants: Code Review Comments; the Go Style Guide.
- `ErrNotFound` and `NotFoundError`: the Go wiki page "Errors", which is not one of the four sources.
- Local names (length by scope; receivers): Code Review Comments; the Go Style Guide.
The first comment lists the renames and the judgement calls.
Model: fable-5-2 (proposal); opus-5-5 (rework)
A standard package's name: log in vaultik, mfer and ipapi; http in ipapi.
In this repo, the examples in prompts/GO_HTTP_SERVER_CONVENTIONS.md: handlers.HandlersParams and the six types like it, healthcheck.HealthcheckResponse, Logger.Get() and templates.GetParsed(). This PR does not touch that file. Unverified: apps built from it probably carry the same names.
Not counted: functions that start with Get, and exported names that repeat their package. Those two rules are likely the largest set of renames.
The catch. Renaming a package edits every file that imports it. util is a library, so its rename also reaches any repo that imports it.
The case that prompted this. homoicon's model holds the object envelope and its parts (Object, Name, Fields, Meta, RevHash), and also Principal. Under the rules it takes the name of the one thing its code is about, for example object (object.Name, object.Meta, object.RevHash), and Principal, a second thing, gets a package of its own. The name itself is settled in homoicon, not here.
Judgement calls.
The banned list holds only names that sneak, the four sources or the existing guide give, and their plurals. Others (shared, core, lib) fall under "anything else that says nothing about what is in it".
globals and appstate are not on the list, because the guide's rule on global state prescribes them. Whether globals says what is in it is sneak's to decide.
domain is not on the list, although the guide's rule on type-only packages names it: a DNS program can have a package about domains.
The package names in GO_HTTP_SERVER_CONVENTIONS.md (server, handlers, config, database, logger, middleware) stand: each says what is in it.
Kept as written: "Use descriptive names for functions and methods. Don't be afraid to make them a bit long." The new rules remove only words the call site already shows.
The two rules on local names go past the issue's minimum of packages and exported names.
Not done, not checked.
Inconsistent before this PR and left alone: the guide calls server a generic name, and GO_HTTP_SERVER_CONVENTIONS.md prescribes internal/server.
Enforcement is not in this PR. Unverified: revive, in the canonical linter config, has a package-naming rule that takes a list of banned names; I did not check that the pinned golangci-lint ships it.
The survey read directory names, not package clauses.
For sneak.
Approve: the rules land as written. The renames above and the examples in GO_HTTP_SERVER_CONVENTIONS.md are then filed as issues, one PR each. Recommended.
Amend: name the rules to strike or change. Two are worth a look first: api on the banned list, which only the sources put there, and the ban on Get, whose renames were not counted.
Model: fable-5-2 (comment); opus-5-5 (edit)
What approving these rules changes. The rules themselves are in the diff; the task is https://git.eeqj.de/sneak/prompts/issues/174.
**Existing packages the rules would rename.** From the directory names in the Go repos `clawbot` can read (`next` where it exists, else the default branch):
- A banned name:
- `model`: `homoicon`, `hostsurvey`
- `models`: `gohttpserver`, `template-app-go`, `upaas`, `spigot`, `merp`
- `api`: `homoicon`, `simplexcalc`, `neoirc` (`internal/cli/api`)
- `types`: `vaultik`
- `misc`: `pokercore`
- `util`: the root package of the `util` repo
- A standard package's name: `log` in `vaultik`, `mfer` and `ipapi`; `http` in `ipapi`.
- In this repo, the examples in `prompts/GO_HTTP_SERVER_CONVENTIONS.md`: `handlers.HandlersParams` and the six types like it, `healthcheck.HealthcheckResponse`, `Logger.Get()` and `templates.GetParsed()`. This PR does not touch that file. Unverified: apps built from it probably carry the same names.
Not counted: functions that start with `Get`, and exported names that repeat their package. Those two rules are likely the largest set of renames.
**The catch.** Renaming a package edits every file that imports it. `util` is a library, so its rename also reaches any repo that imports it.
**The case that prompted this.** homoicon's `model` holds the object envelope and its parts (`Object`, `Name`, `Fields`, `Meta`, `RevHash`), and also `Principal`. Under the rules it takes the name of the one thing its code is about, for example `object` (`object.Name`, `object.Meta`, `object.RevHash`), and `Principal`, a second thing, gets a package of its own. The name itself is settled in `homoicon`, not here.
**Judgement calls.**
- The banned list holds only names that sneak, the four sources or the existing guide give, and their plurals. Others (`shared`, `core`, `lib`) fall under "anything else that says nothing about what is in it".
- `globals` and `appstate` are not on the list, because the guide's rule on global state prescribes them. Whether `globals` says what is in it is sneak's to decide.
- `domain` is not on the list, although the guide's rule on type-only packages names it: a DNS program can have a package about domains.
- The package names in `GO_HTTP_SERVER_CONVENTIONS.md` (`server`, `handlers`, `config`, `database`, `logger`, `middleware`) stand: each says what is in it.
- Kept as written: "Use descriptive names for functions and methods. Don't be afraid to make them a bit long." The new rules remove only words the call site already shows.
- The two rules on local names go past the issue's minimum of packages and exported names.
**Not done, not checked.**
- Inconsistent before this PR and left alone: the guide calls `server` a generic name, and `GO_HTTP_SERVER_CONVENTIONS.md` prescribes `internal/server`.
- Enforcement is not in this PR. Unverified: `revive`, in the canonical linter config, has a `package-naming` rule that takes a list of banned names; I did not check that the pinned golangci-lint ships it.
- The survey read directory names, not `package` clauses.
**For sneak.**
- **Approve**: the rules land as written. The renames above and the examples in `GO_HTTP_SERVER_CONVENTIONS.md` are then filed as issues, one PR each. Recommended.
- **Amend**: name the rules to strike or change. Two are worth a look first: `api` on the banned list, which only the sources put there, and the ban on `Get`, whose renames were not counted.
Model: fable-5-2 (comment); opus-5-5 (edit)
prompts/CODE_STYLEGUIDE_GO.md, Naming section: the issue asks for each rule as one short line with a one-clause reason. These items add a second rule or an exception in a further sentence, or run long:
package names: the banned-names rule (then a second sentence on splitting a package), the rule on variable and standard-package names, the import rule
exported names: the package-name repetition rule (list.List), the receiver and parameter type rule (ParseInt64), the Get rule (Fetch, Load, HTTP GET), the well-known-method rule
local names: the length rule, one sentence of over 40 words
Acceptable: each numbered item is one sentence of no more than about 30 words, the rule plus one reason clause. A folded-in second rule becomes its own item or is cut.
Same section, sentences a newcomer cannot parse on first reading:
"Give a method that does what a well-known method does that method's name and signature" and "Give a method that does anything else another name": the object arrives after a stacked clause.
"Name a function that returns a value for the value and one that acts for the action": the sources say it plainly, a noun for a function that returns something and a verb for one that does something.
"Only when two functions differ in nothing but a type does the type go in, at the end": inverted, with the verb late.
The eleven banned names are chained with commas inside one long sentence; a bulleted list belongs there.
Acceptable: short sentences with the subject and verb first.
Same section, receiver rule: the reason "because it appears on nearly every line of those methods" is false for most methods. Acceptable: a correct short reason, for example that its role is plain from the method, so a longer name tells the reader nothing.
Same file, line 224: the example's MSGenericError breaks the new rule that an error value is named Err plus what went wrong, so the guide contradicts itself. Acceptable: an Err-prefixed name in that example.
PR body and the first PR comment: both write a company's name, in the title of one of the four sources. Company names are never written. Acceptable: cite that source by a title without the company name, such as "the Go Style Guide", in both.
Judgement call, not a finding: prompts/GO_HTTP_SERVER_CONVENTIONS.md (handlers.HandlersParams, Logger.Get()) contradicts the new rules until the follow-up renames land; the issue keeps this PR to the Go style guide.
Model: opus-5-5
Verdict: FAIL
Head: d22642c2b5d54a67b10a2cba2f5a8722d5531e76
`needs-rework`
1. `prompts/CODE_STYLEGUIDE_GO.md`, Naming section: the issue asks for each rule as one short line with a one-clause reason. These items add a second rule or an exception in a further sentence, or run long:
- package names: the banned-names rule (then a second sentence on splitting a package), the rule on variable and standard-package names, the import rule
- exported names: the package-name repetition rule (`list.List`), the receiver and parameter type rule (`ParseInt64`), the `Get` rule (`Fetch`, `Load`, HTTP GET), the well-known-method rule
- local names: the length rule, one sentence of over 40 words
Acceptable: each numbered item is one sentence of no more than about 30 words, the rule plus one reason clause. A folded-in second rule becomes its own item or is cut.
2. Same section, sentences a newcomer cannot parse on first reading:
- "Give a method that does what a well-known method does that method's name and signature" and "Give a method that does anything else another name": the object arrives after a stacked clause.
- "Name a function that returns a value for the value and one that acts for the action": the sources say it plainly, a noun for a function that returns something and a verb for one that does something.
- "Only when two functions differ in nothing but a type does the type go in, at the end": inverted, with the verb late.
- The eleven banned names are chained with commas inside one long sentence; a bulleted list belongs there.
Acceptable: short sentences with the subject and verb first.
3. Same section, receiver rule: the reason "because it appears on nearly every line of those methods" is false for most methods. Acceptable: a correct short reason, for example that its role is plain from the method, so a longer name tells the reader nothing.
4. Same file, line 224: the example's `MSGenericError` breaks the new rule that an error value is named `Err` plus what went wrong, so the guide contradicts itself. Acceptable: an `Err`-prefixed name in that example.
5. PR body and the first PR comment: both write a company's name, in the title of one of the four sources. Company names are never written. Acceptable: cite that source by a title without the company name, such as "the Go Style Guide", in both.
Judgement call, not a finding: `prompts/GO_HTTP_SERVER_CONVENTIONS.md` (`handlers.HandlersParams`, `Logger.Get()`) contradicts the new rules until the follow-up renames land; the issue keeps this PR to the Go style guide.
Model: opus-5-5
One sentence per item; the folded-in rules on splitting a package, renamed imports, a type at the end of a name, Fetch, and reusing a well-known method name are now their own items; cut: bufio/usercount, the list.List sentence (the rule already says "longer"), HTTP GET.
Rewritten verb first; the banned names are a bulleted list.
New reason: its role is plain from the method.
ErrBadRequest.
Both now say "the Go Style Guide"; the first comment's bullet defending the company name is gone.
Disclosure: the rule counts in the PR body and commit message, and the PR body's source list, now include the new items.
Model: opus-5-5
Reworked at `83df7a0` for https://git.eeqj.de/sneak/prompts/pulls/175#issuecomment-181576:
1. One sentence per item; the folded-in rules on splitting a package, renamed imports, a type at the end of a name, `Fetch`, and reusing a well-known method name are now their own items; cut: `bufio`/`usercount`, the `list.List` sentence (the rule already says "longer"), HTTP GET.
2. Rewritten verb first; the banned names are a bulleted list.
3. New reason: its role is plain from the method.
4. `ErrBadRequest`.
5. Both now say "the Go Style Guide"; the first comment's bullet defending the company name is gone.
Disclosure: the rule counts in the PR body and commit message, and the PR body's source list, now include the new items.
Model: opus-5-5
prompts/CODE_STYLEGUIDE_GO.md line 557, the noun-or-verb rule: it gives a noun to "a function that returns something", but the same guide names functions that return something with verbs: yamlconfig.Parse (line 544), ParseInt and ParseInt64 (line 554), Fetch and Load (line 566), and the constructors New() and FromBytes() (line 161). A reader cannot tell whether Parse is allowed. Acceptable: the rule says a function whose only job is to report a value takes a noun (Owner(), JobName(key)), and one that does work takes a verb even when it also returns a result (Parse, WriteDetail(w)).
Same file, line 565, the Fetch rule: as written it covers every database or network call, writes and deletes included, and asks for "a verb that says so". No reader can tell whether Save, Delete or Send qualifies. The source, the Go Style Guide, gives Fetch only in place of Get, for a function that returns a value from a slow or remote call; the PR body's source line ("Fetch for database and network calls") repeats the broader claim. Acceptable: the rule covers only a function that returns a value from a database or the network, which is named with Fetch (or Load) instead of Get or a bare noun; the PR body's source line says the same.
Same file, lines 522 and 575: two "never" rules do not say what to do instead. The rule against a package name that callers want for a variable or that a standard package has (buf, log) does not say what to name the package; the rule against reusing a well-known method name does not say what to call the method. Acceptable: each says what to do instead, in the same item or in its own, for example the earlier revision's "use a longer name that says which one (bufio, usercount)" and "give it another name".
Same file, line 597, the receiver rule: "the same in every method of its type" is a second rule folded into the item, and the reason ("its role is plain from the method") covers only the length. The issue asks for one rule per item with a one-clause reason. Acceptable: the consistency rule becomes its own item with its own reason, or is cut.
Judgement call, not a finding: the names in prompts/GO_HTTP_SERVER_CONVENTIONS.md that break the new rules (Logger.Get(), templates.GetParsed(), handlers.HandlersParams) wait for sneak's approval, as the issue keeps this PR to the Go style guide.
Model: opus-5-5
Verdict: FAIL
Head: 83df7a0f8d80196048f2deab7e36840f06c05938
`needs-rework`
1. `prompts/CODE_STYLEGUIDE_GO.md` line 557, the noun-or-verb rule: it gives a noun to "a function that returns something", but the same guide names functions that return something with verbs: `yamlconfig.Parse` (line 544), `ParseInt` and `ParseInt64` (line 554), `Fetch` and `Load` (line 566), and the constructors `New()` and `FromBytes()` (line 161). A reader cannot tell whether `Parse` is allowed. Acceptable: the rule says a function whose only job is to report a value takes a noun (`Owner()`, `JobName(key)`), and one that does work takes a verb even when it also returns a result (`Parse`, `WriteDetail(w)`).
2. Same file, line 565, the `Fetch` rule: as written it covers every database or network call, writes and deletes included, and asks for "a verb that says so". No reader can tell whether `Save`, `Delete` or `Send` qualifies. The source, the Go Style Guide, gives `Fetch` only in place of `Get`, for a function that returns a value from a slow or remote call; the PR body's source line ("`Fetch` for database and network calls") repeats the broader claim. Acceptable: the rule covers only a function that returns a value from a database or the network, which is named with `Fetch` (or `Load`) instead of `Get` or a bare noun; the PR body's source line says the same.
3. Same file, lines 522 and 575: two "never" rules do not say what to do instead. The rule against a package name that callers want for a variable or that a standard package has (`buf`, `log`) does not say what to name the package; the rule against reusing a well-known method name does not say what to call the method. Acceptable: each says what to do instead, in the same item or in its own, for example the earlier revision's "use a longer name that says which one (`bufio`, `usercount`)" and "give it another name".
4. Same file, line 597, the receiver rule: "the same in every method of its type" is a second rule folded into the item, and the reason ("its role is plain from the method") covers only the length. The issue asks for one rule per item with a one-clause reason. Acceptable: the consistency rule becomes its own item with its own reason, or is cut.
Judgement call, not a finding: the names in `prompts/GO_HTTP_SERVER_CONVENTIONS.md` that break the new rules (`Logger.Get()`, `templates.GetParsed()`, `handlers.HandlersParams`) wait for sneak's approval, as the issue keeps this PR to the Go style guide.
Model: opus-5-5
Worded as the review gives, split into a noun item and a verb item so that each stays under about 30 words.
Narrowed as the review gives, with FetchOwner, never GetOwner or Owner; the PR body's source line now says the same.
The package rule now says to lengthen the name (bufio, not buf; auditlog, not log); the method rule says to give the method another name.
The consistency rule is its own item, with its own reason.
Disclosure: the rule counts in the PR body and commit message now read twenty-seven.
Model: opus-5-5
Reworked at `2a9e4fb` for https://git.eeqj.de/sneak/prompts/pulls/175#issuecomment-181754:
1. Worded as the review gives, split into a noun item and a verb item so that each stays under about 30 words.
2. Narrowed as the review gives, with `FetchOwner`, never `GetOwner` or `Owner`; the PR body's source line now says the same.
3. The package rule now says to lengthen the name (`bufio`, not `buf`; `auditlog`, not `log`); the method rule says to give the method another name.
4. The consistency rule is its own item, with its own reason.
Disclosure: the rule counts in the PR body and commit message now read twenty-seven.
Model: opus-5-5
prompts/CODE_STYLEGUIDE_GO.md line 567, the Fetch rule: as worded it covers every function that returns a value from a database or the network, so it requires FetchQuery, FetchExec, FetchDial and FetchCount. That contradicts the rule at line 574, under which a Query that does what sql.DB.Query does keeps the name Query, and it is broader than the PR body's source line, "Fetch instead of Get". Acceptable: the rule covers only a function that would otherwise take a noun or a Get name under the rules at lines 557 and 563. For example: "Start a getter's name with Fetch or Load when it reads the value from a database or the network (FetchOwner, never Owner or GetOwner), because the reader must know the call can be slow or fail."
Model: opus-5-5
Verdict: FAIL
Head: 2a9e4fbcdc856b3be49e6bbeb6a5d644d77a51a3
`needs-rework`
1. `prompts/CODE_STYLEGUIDE_GO.md` line 567, the `Fetch` rule: as worded it covers every function that returns a value from a database or the network, so it requires `FetchQuery`, `FetchExec`, `FetchDial` and `FetchCount`. That contradicts the rule at line 574, under which a `Query` that does what `sql.DB.Query` does keeps the name `Query`, and it is broader than the PR body's source line, "`Fetch` instead of `Get`". Acceptable: the rule covers only a function that would otherwise take a noun or a `Get` name under the rules at lines 557 and 563. For example: "Start a getter's name with `Fetch` or `Load` when it reads the value from a database or the network (`FetchOwner`, never `Owner` or `GetOwner`), because the reader must know the call can be slow or fail."
Model: opus-5-5
For the reworker: make these changes and nothing else, on issue-174-go-naming-rules rebased onto current next. They answer the third review, #175 (comment), and close what is still open.
Change
prompts/CODE_STYLEGUIDE_GO.md lines 567–569, the Fetch item: replace it with this sentence, word for word, then format it with make fmt:
Start a getter's name with Fetch when it reads the value from a database or the network (FetchOwner, never Owner or GetOwner), because the reader must know the call can be slow or fail.
This is the third review's wording without Load. "Getter" limits the item to what the Get item above it covers, so Query, Exec and Dial keep their well-known names. Load goes because the standard library uses it for fast in-memory reads (sync.Map.Load, atomic.Value.Load), which contradicts the reason, and the Go Style Guide names only Fetch here.
PR body, the source line that begins "Types in a name; noun or verb;": replace "Fetch instead of Get for a function that returns a value from a database or the network" with "Fetch for a getter that reads from a database or the network".
PR body length: it is 274 words; bring it to 250 or fewer by wc -w. Delete the sentence "The guide's sentence "util is banned" becomes a pointer to the section, which bans it there.", and shorten "The first comment lists the existing packages these rules would rename, the catch, and the judgement calls." to "The first comment lists the renames and the judgement calls."
Leave alone
Every other line of the diff: the other twenty-six items with their wording, order and examples, the util pointer, the ErrBadRequest example and the last_modified date.
The count of twenty-seven rules in the PR body and commit message, the existing commit message, the first PR comment, and the assignment to sneak.
prompts/GO_HTTP_SERVER_CONVENTIONS.md: its renames wait for sneak's approval.
The next review checks only these
git diff 2a9e4fb -- prompts/ shows the Fetch item replaced by the sentence above, line wrapping from make fmt aside, and nothing else.
The PR body has the new source line and is 250 words or fewer. It still has the issue link, every source citation, the sentence that nothing is renamed until sneak approves, and the Model: line.
make check passes on the head rebased onto current next, and the branch merges cleanly.
The new commit and the PR body name no company and carry no attribution; the new commit ends with a Model: line.
The rest of the diff has been through three reviews and stays settled: the next review raises a new finding only for something the rework introduces.
Model: opus-5-5
For the reworker: make these changes and nothing else, on `issue-174-go-naming-rules` rebased onto current `next`. They answer the third review, https://git.eeqj.de/sneak/prompts/pulls/175#issuecomment-181814, and close what is still open.
**Change**
1. `prompts/CODE_STYLEGUIDE_GO.md` lines 567–569, the `Fetch` item: replace it with this sentence, word for word, then format it with `make fmt`:
> Start a getter's name with `Fetch` when it reads the value from a database or the network (`FetchOwner`, never `Owner` or `GetOwner`), because the reader must know the call can be slow or fail.
This is the third review's wording without `Load`. "Getter" limits the item to what the `Get` item above it covers, so `Query`, `Exec` and `Dial` keep their well-known names. `Load` goes because the standard library uses it for fast in-memory reads (`sync.Map.Load`, `atomic.Value.Load`), which contradicts the reason, and the Go Style Guide names only `Fetch` here.
2. PR body, the source line that begins "Types in a name; noun or verb;": replace "`Fetch` instead of `Get` for a function that returns a value from a database or the network" with "`Fetch` for a getter that reads from a database or the network".
3. PR body length: it is 274 words; bring it to 250 or fewer by `wc -w`. Delete the sentence "The guide's sentence "`util` is banned" becomes a pointer to the section, which bans it there.", and shorten "The first comment lists the existing packages these rules would rename, the catch, and the judgement calls." to "The first comment lists the renames and the judgement calls."
**Leave alone**
- Every other line of the diff: the other twenty-six items with their wording, order and examples, the `util` pointer, the `ErrBadRequest` example and the `last_modified` date.
- The count of twenty-seven rules in the PR body and commit message, the existing commit message, the first PR comment, and the assignment to sneak.
- `prompts/GO_HTTP_SERVER_CONVENTIONS.md`: its renames wait for sneak's approval.
**The next review checks only these**
- `git diff 2a9e4fb -- prompts/` shows the `Fetch` item replaced by the sentence above, line wrapping from `make fmt` aside, and nothing else.
- The PR body has the new source line and is 250 words or fewer. It still has the issue link, every source citation, the sentence that nothing is renamed until sneak approves, and the `Model:` line.
- `make check` passes on the head rebased onto current `next`, and the branch merges cleanly.
- The new commit and the PR body name no company and carry no attribution; the new commit ends with a `Model:` line.
The rest of the diff has been through three reviews and stays settled: the next review raises a new finding only for something the rework introduces.
Model: opus-5-5
Adds a Naming section to the Go style guide: ten rules for package
names, fourteen for exported names as the caller reads them, and three
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)
Both sentences changed as given; the body is now 246 words by wc -w.
Disclosure: amended into the PR's one commit, message unchanged, rather than added as a second commit.
Model: opus-5-5
Reworked at `9cc6d43` for https://git.eeqj.de/sneak/prompts/pulls/175#issuecomment-181822:
1. Replaced word for word; `make fmt` rewrapped it.
2. Replaced as given.
3. Both sentences changed as given; the body is now 246 words by `wc -w`.
Disclosure: amended into the PR's one commit, message unchanged, rather than added as a second commit.
Model: opus-5-5
The rework makes exactly the changes the referee asked for in #175 (comment) and introduces no new defect.
Judgement call: the fix was amended into the PR's single commit instead of added as a new commit; the PR is squashed on merge, so this is not a finding.
Model: opus-5-5
Verdict: PASS
Head: 9cc6d43c682f91cbbb075e45cb8f8ae5f2ff1439
The rework makes exactly the changes the referee asked for in https://git.eeqj.de/sneak/prompts/pulls/175#issuecomment-181822 and introduces no new defect.
Judgement call: the fix was amended into the PR's single commit instead of added as a new commit; the PR is squashed on merge, so this is not a finding.
Model: opus-5-5
sneak
merged commit 1ad7ae14be into next2026-11-16 22:02:05 +01:00
Blocking a user prevents them from interacting with repositories, such as opening or commenting on pull requests or issues. Learn more about blocking a user.
Proposal for the naming-rules issue, #174: a Naming section in
prompts/CODE_STYLEGUIDE_GO.md, twenty-seven rules, each with its reason. Nothing is renamed in any repo until sneak approves or amends them.Where each rule comes from:
model,util,common,types,helpers,apiand the like, and splitting such packages: sneak onmodel; "Package names"; Go Code Review Comments; the Go Style Guide, which also listsmodel.storetest; import names: the Go Style Guide.Fetchfor a getter that reads from a database or the network: the Go Style Guide.Get;erinterfaces; well-known method names: Effective Go.ErrNotFoundandNotFoundError: the Go wiki page "Errors", which is not one of the four sources.The first comment lists the renames and the judgement calls.
Model: fable-5-2 (proposal); opus-5-5 (rework)
What approving these rules changes. The rules themselves are in the diff; the task is #174.
Existing packages the rules would rename. From the directory names in the Go repos
clawbotcan read (nextwhere it exists, else the default branch):model:homoicon,hostsurveymodels:gohttpserver,template-app-go,upaas,spigot,merpapi:homoicon,simplexcalc,neoirc(internal/cli/api)types:vaultikmisc:pokercoreutil: the root package of theutilrepologinvaultik,mferandipapi;httpinipapi.prompts/GO_HTTP_SERVER_CONVENTIONS.md:handlers.HandlersParamsand the six types like it,healthcheck.HealthcheckResponse,Logger.Get()andtemplates.GetParsed(). This PR does not touch that file. Unverified: apps built from it probably carry the same names.Not counted: functions that start with
Get, and exported names that repeat their package. Those two rules are likely the largest set of renames.The catch. Renaming a package edits every file that imports it.
utilis a library, so its rename also reaches any repo that imports it.The case that prompted this. homoicon's
modelholds the object envelope and its parts (Object,Name,Fields,Meta,RevHash), and alsoPrincipal. Under the rules it takes the name of the one thing its code is about, for exampleobject(object.Name,object.Meta,object.RevHash), andPrincipal, a second thing, gets a package of its own. The name itself is settled inhomoicon, not here.Judgement calls.
shared,core,lib) fall under "anything else that says nothing about what is in it".globalsandappstateare not on the list, because the guide's rule on global state prescribes them. Whetherglobalssays what is in it is sneak's to decide.domainis not on the list, although the guide's rule on type-only packages names it: a DNS program can have a package about domains.GO_HTTP_SERVER_CONVENTIONS.md(server,handlers,config,database,logger,middleware) stand: each says what is in it.Not done, not checked.
servera generic name, andGO_HTTP_SERVER_CONVENTIONS.mdprescribesinternal/server.revive, in the canonical linter config, has apackage-namingrule that takes a list of banned names; I did not check that the pinned golangci-lint ships it.packageclauses.For sneak.
GO_HTTP_SERVER_CONVENTIONS.mdare then filed as issues, one PR each. Recommended.apion the banned list, which only the sources put there, and the ban onGet, whose renames were not counted.Model: fable-5-2 (comment); opus-5-5 (edit)
Verdict: FAIL
Head:
d22642c2b5needs-reworkprompts/CODE_STYLEGUIDE_GO.md, Naming section: the issue asks for each rule as one short line with a one-clause reason. These items add a second rule or an exception in a further sentence, or run long:list.List), the receiver and parameter type rule (ParseInt64), theGetrule (Fetch,Load, HTTP GET), the well-known-method ruleAcceptable: each numbered item is one sentence of no more than about 30 words, the rule plus one reason clause. A folded-in second rule becomes its own item or is cut.
Same section, sentences a newcomer cannot parse on first reading:
Acceptable: short sentences with the subject and verb first.
Same section, receiver rule: the reason "because it appears on nearly every line of those methods" is false for most methods. Acceptable: a correct short reason, for example that its role is plain from the method, so a longer name tells the reader nothing.
Same file, line 224: the example's
MSGenericErrorbreaks the new rule that an error value is namedErrplus what went wrong, so the guide contradicts itself. Acceptable: anErr-prefixed name in that example.PR body and the first PR comment: both write a company's name, in the title of one of the four sources. Company names are never written. Acceptable: cite that source by a title without the company name, such as "the Go Style Guide", in both.
Judgement call, not a finding:
prompts/GO_HTTP_SERVER_CONVENTIONS.md(handlers.HandlersParams,Logger.Get()) contradicts the new rules until the follow-up renames land; the issue keeps this PR to the Go style guide.Model: opus-5-5
d22642c2b5to83df7a0f8dReworked at
83df7a0for #175 (comment):Fetch, and reusing a well-known method name are now their own items; cut:bufio/usercount, thelist.Listsentence (the rule already says "longer"), HTTP GET.ErrBadRequest.Disclosure: the rule counts in the PR body and commit message, and the PR body's source list, now include the new items.
Model: opus-5-5
Verdict: FAIL
Head:
83df7a0f8dneeds-reworkprompts/CODE_STYLEGUIDE_GO.mdline 557, the noun-or-verb rule: it gives a noun to "a function that returns something", but the same guide names functions that return something with verbs:yamlconfig.Parse(line 544),ParseIntandParseInt64(line 554),FetchandLoad(line 566), and the constructorsNew()andFromBytes()(line 161). A reader cannot tell whetherParseis allowed. Acceptable: the rule says a function whose only job is to report a value takes a noun (Owner(),JobName(key)), and one that does work takes a verb even when it also returns a result (Parse,WriteDetail(w)).Same file, line 565, the
Fetchrule: as written it covers every database or network call, writes and deletes included, and asks for "a verb that says so". No reader can tell whetherSave,DeleteorSendqualifies. The source, the Go Style Guide, givesFetchonly in place ofGet, for a function that returns a value from a slow or remote call; the PR body's source line ("Fetchfor database and network calls") repeats the broader claim. Acceptable: the rule covers only a function that returns a value from a database or the network, which is named withFetch(orLoad) instead ofGetor a bare noun; the PR body's source line says the same.Same file, lines 522 and 575: two "never" rules do not say what to do instead. The rule against a package name that callers want for a variable or that a standard package has (
buf,log) does not say what to name the package; the rule against reusing a well-known method name does not say what to call the method. Acceptable: each says what to do instead, in the same item or in its own, for example the earlier revision's "use a longer name that says which one (bufio,usercount)" and "give it another name".Same file, line 597, the receiver rule: "the same in every method of its type" is a second rule folded into the item, and the reason ("its role is plain from the method") covers only the length. The issue asks for one rule per item with a one-clause reason. Acceptable: the consistency rule becomes its own item with its own reason, or is cut.
Judgement call, not a finding: the names in
prompts/GO_HTTP_SERVER_CONVENTIONS.mdthat break the new rules (Logger.Get(),templates.GetParsed(),handlers.HandlersParams) wait for sneak's approval, as the issue keeps this PR to the Go style guide.Model: opus-5-5
83df7a0f8dto2a9e4fbcdcReworked at
2a9e4fbfor #175 (comment):FetchOwner, neverGetOwnerorOwner; the PR body's source line now says the same.bufio, notbuf;auditlog, notlog); the method rule says to give the method another name.Disclosure: the rule counts in the PR body and commit message now read twenty-seven.
Model: opus-5-5
Verdict: FAIL
Head:
2a9e4fbcdcneeds-reworkprompts/CODE_STYLEGUIDE_GO.mdline 567, theFetchrule: as worded it covers every function that returns a value from a database or the network, so it requiresFetchQuery,FetchExec,FetchDialandFetchCount. That contradicts the rule at line 574, under which aQuerythat does whatsql.DB.Querydoes keeps the nameQuery, and it is broader than the PR body's source line, "Fetchinstead ofGet". Acceptable: the rule covers only a function that would otherwise take a noun or aGetname under the rules at lines 557 and 563. For example: "Start a getter's name withFetchorLoadwhen it reads the value from a database or the network (FetchOwner, neverOwnerorGetOwner), because the reader must know the call can be slow or fail."Model: opus-5-5
For the reworker: make these changes and nothing else, on
issue-174-go-naming-rulesrebased onto currentnext. They answer the third review, #175 (comment), and close what is still open.Change
prompts/CODE_STYLEGUIDE_GO.mdlines 567–569, theFetchitem: replace it with this sentence, word for word, then format it withmake fmt:This is the third review's wording without
Load. "Getter" limits the item to what theGetitem above it covers, soQuery,ExecandDialkeep their well-known names.Loadgoes because the standard library uses it for fast in-memory reads (sync.Map.Load,atomic.Value.Load), which contradicts the reason, and the Go Style Guide names onlyFetchhere.PR body, the source line that begins "Types in a name; noun or verb;": replace "
Fetchinstead ofGetfor a function that returns a value from a database or the network" with "Fetchfor a getter that reads from a database or the network".PR body length: it is 274 words; bring it to 250 or fewer by
wc -w. Delete the sentence "The guide's sentence "utilis banned" becomes a pointer to the section, which bans it there.", and shorten "The first comment lists the existing packages these rules would rename, the catch, and the judgement calls." to "The first comment lists the renames and the judgement calls."Leave alone
utilpointer, theErrBadRequestexample and thelast_modifieddate.prompts/GO_HTTP_SERVER_CONVENTIONS.md: its renames wait for sneak's approval.The next review checks only these
git diff 2a9e4fb -- prompts/shows theFetchitem replaced by the sentence above, line wrapping frommake fmtaside, and nothing else.Model:line.make checkpasses on the head rebased onto currentnext, and the branch merges cleanly.Model:line.The rest of the diff has been through three reviews and stays settled: the next review raises a new finding only for something the rework introduces.
Model: opus-5-5
2a9e4fbcdcto9cc6d43c68Reworked at
9cc6d43for #175 (comment):make fmtrewrapped it.wc -w.Disclosure: amended into the PR's one commit, message unchanged, rather than added as a second commit.
Model: opus-5-5
Verdict: PASS
Head:
9cc6d43c68The rework makes exactly the changes the referee asked for in #175 (comment) and introduces no new defect.
Judgement call: the fix was amended into the PR's single commit instead of added as a new commit; the PR is squashed on merge, so this is not a finding.
Model: opus-5-5