CODE_STYLEGUIDE_GO: propose naming rules for packages and exported names (closes #174) #175

Open
clawbot wants to merge 1 commits from issue-174-go-naming-rules into next
pull from: issue-174-go-naming-rules
Collaborator

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
clawbot added the needs-review label 2026-11-16 06:21:53 +01:00
sneak was assigned by clawbot 2026-11-16 06:21:53 +01:00
clawbot added 1 commit 2026-11-16 06:21:53 +01:00
CODE_STYLEGUIDE_GO: propose naming rules (closes #174)
check / check (push) Successful in 1m24s
d22642c2b5
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
Author
Collaborator

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 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

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
Author
Collaborator

Verdict: FAIL
Head: d22642c2b5

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

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
All checks were successful
check / check (push) Successful in 1m24s
You are not authorized to merge this pull request.
This pull request can be merged automatically.
View command line instructions

Checkout

From your project repository, check out a new branch and test the changes.
git fetch -u origin issue-174-go-naming-rules:issue-174-go-naming-rules
git checkout issue-174-go-naming-rules
Sign in to join this conversation.