Proposal for the naming-rules issue, #174: a Naming section in prompts/CODE_STYLEGUIDE_GO.md, twenty 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: sneak on model; "Package names"; Go Code Review Comments; the Google Go style guide, which also lists model.
No name a caller wants for a variable or a standard package has: "Package names"; the Google guide.
Directory named as the package: Effective Go.
Test-support packages named like storetest; imports under their own name: the Google guide.
Exported names
No package name repeated; the same plain name in two packages: Effective Go; "Package names"; Code Review Comments.
No receiver, parameter or result type in a name; value or action: the Google guide.
No Get; er interfaces; well-known method names: Effective Go.
Initialisms; MixedCaps constants: Code Review Comments; the Google 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 Google guide.
The guide's sentence "util is banned" becomes a pointer to the section, which bans it there.
The first comment lists the existing packages these rules would rename, the catch, and the judgement calls.
Model: fable-5-2
Proposal for the naming-rules issue, https://git.eeqj.de/sneak/prompts/issues/174: a Naming section in `prompts/CODE_STYLEGUIDE_GO.md`, twenty 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: sneak on `model`; "Package names"; Go Code Review Comments; the Google Go style guide, which also lists `model`.
- No name a caller wants for a variable or a standard package has: "Package names"; the Google guide.
- Directory named as the package: Effective Go.
- Test-support packages named like `storetest`; imports under their own name: the Google guide.
- Exported names
- No package name repeated; the same plain name in two packages: Effective Go; "Package names"; Code Review Comments.
- No receiver, parameter or result type in a name; value or action: the Google guide.
- No `Get`; `er` interfaces; well-known method names: Effective Go.
- Initialisms; MixedCaps constants: Code Review Comments; the Google 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 Google guide.
The guide's sentence "`util` is banned" becomes a pointer to the section, which bans it there.
The first comment lists the existing packages these rules would rename, the catch, and the judgement calls.
Model: fable-5-2
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
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.
The PR body names the Google Go style guide, since the issue asks for sources by name. The rule against writing company names is read as not covering a source's title.
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
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.
- The PR body names the Google Go style guide, since the issue asks for sources by name. The rule against writing company names is read as not covering a source's title.
**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
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
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 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: sneak onmodel; "Package names"; Go Code Review Comments; the Google Go style guide, which also listsmodel.storetest; imports under their own name: the Google guide.Get;erinterfaces; well-known method names: Effective Go.ErrNotFoundandNotFoundError: the Go wiki page "Errors", which is not one of the four sources.The guide's sentence "
utilis banned" becomes a pointer to the section, which bans it there.The first comment lists the existing packages these rules would rename, the catch, and the judgement calls.
Model: fable-5-2
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
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
View command line instructions
Checkout
From your project repository, check out a new branch and test the changes.