Author SHA1 Message Date
clawbot 9cc6d43c68 CODE_STYLEGUIDE_GO: propose naming rules (closes #174)
check / check (push) Successful in 29s
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)
2026-11-16 07:26:13 +00:00
clawbot 69d38ba6de README: remove the Template Repos section (closes #153)
check / check (push) Successful in 1m47s
Every repository the section linked returned 404 to a signed-out
reader: `template-app-js` and `template-app-python` do not exist, and
`template-app-go` is private. The section is gone, intro included.

Model: opus-5-5
2026-11-15 17:39:12 +01:00
clawbot 198b896a53 Correct the phase-build comments in script/lint and script/test (closes #141)
check / check (push) Successful in 35s
The comments said a phase that is not the last stage is built only when
--target names it. The canonical Dockerfile's last stage copies from both
phases, so a plain build builds them too. The comments now say what
--target does in every repository: it builds that phase and the stages
it depends on, nothing else. The headers no longer say each script
builds its phase alone, which is false wherever the phase depends on
another stage.

Model: opus-5-5
2026-11-15 17:09:08 +01:00
clawbot 11245b85ca script/install-precommit: write the hook through $hook (closes #139)
check / check (push) Successful in 1m41s
The script set hook and then repeated the path literally, so shellcheck
reported the variable as unused (SC2034).

Model: opus-5-5
2026-11-15 14:23:52 +01:00
clawbot 02632a5682 Drop the TODO.md union-merge rule (closes #169)
check / check (push) Successful in 1m46s
The rule and its comment existed only so concurrent PRs could each add a
Completed Steps entry to `TODO.md`. That work log is gone; `TODO.md` now
holds only open work, so it merges normally again.

Model: opus-5-5
2026-11-15 07:38:36 +01:00
clawbot fdf517a1f7 TODO.md: remove the work log, keep only open work (closes #167)
check / check (push) Successful in 1m44s
Drop the Completed Steps log and the finished "commit this TODO.md"
item. Git keeps the history. The Workflow section now says to delete
the finished Next Step, as the standard Workflow block does.

Model: opus-5-5
2026-11-15 07:08:44 +01:00
6 changed files with 127 additions and 32 deletions

No files matched your search

-5
View File
@@ -1,7 +1,2 @@
# Every PR adds an entry at the top of TODO.md's Completed Steps; union keeps
# both sides instead of conflicting. Git never reports a conflict here: read
# the merged entries after every merge or rebase.
TODO.md merge=union
# yarn's release file is one opaque file in diffs and merges. # yarn's release file is one opaque file in diffs and merges.
.yarn/releases/** binary .yarn/releases/** binary
-16
View File
@@ -177,22 +177,6 @@ subdirectory. Each file contains one or more related prompts or policy
documents. There is no build step or runtime component; the prompts are consumed documents. There is no build step or runtime component; the prompts are consumed
by copying them into other projects or referencing them directly. by copying them into other projects or referencing them directly.
## Template Repos
These template repositories implement the policies defined in this repo and
serve as starting points for new projects. They must be kept in sync when
policies change.
- **[template-app-go](https://git.eeqj.de/sneak/template-app-go)** — Go HTTP
server template (Uber fx, chi, SQLite, session auth, Prometheus metrics)
- **[template-app-js](https://git.eeqj.de/sneak/template-app-js)** — JavaScript
SPA template (Vite, Tailwind CSS v4, nginx Docker deployment)
- **[template-app-python](https://git.eeqj.de/sneak/template-app-python)** —
Python web application template (FastAPI, uvicorn, pytest, black, ruff)
When updating policies in this repo, also update the template repos to match
(Makefile targets, Dockerfile conventions, CI workflows, required files, etc.).
## See Also ## See Also
- **[clawpub](https://git.eeqj.de/sneak/clawpub)** — Real-world examples, - **[clawpub](https://git.eeqj.de/sneak/clawpub)** — Real-world examples,
+119 -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,122 @@ 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. Lengthen a package name that callers want for a variable or that a widely
used standard package has (`bufio`, not `buf`; `auditlog`, not `log`),
because importers must otherwise 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 only reports a value (`Owner()`,
`JobName(key)`), so that a call reads as the value it gives.
1. Use a verb for a function that does work, even when it also returns a result
(`Parse`, `WriteDetail(w)`), so that a call reads as the work it 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. 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.
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. Give another name to a method that differs in meaning or signature from a
well-known method of the same name (`Read`, `Write`, `Close`, `String`),
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, never `this`, `self` or `me`,
because its role is plain from the method.
1. Use the same receiver name in every method of a type, so that the name
always means the receiver.
# 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
+2 -2
View File
@@ -8,8 +8,8 @@ ROOT="$(cd "$(dirname "$0")/.." && pwd -P)"
main() { main() {
cd "$ROOT" cd "$ROOT"
hook=".git/hooks/pre-commit" hook=".git/hooks/pre-commit"
printf '#!/bin/sh\nset -e\nscript/precommit\n' > .git/hooks/pre-commit printf '#!/bin/sh\nset -e\nscript/precommit\n' > "$hook"
chmod +x .git/hooks/pre-commit chmod +x "$hook"
echo "pre-commit hook installed: runs script/precommit" echo "pre-commit hook installed: runs script/precommit"
} }
+3 -3
View File
@@ -1,11 +1,11 @@
#!/bin/sh #!/bin/sh
# script/lint: run the linter. Linting is a phase of the Dockerfile and # script/lint: run the linter. Linting is a phase of the Dockerfile and
# this builds that phase alone; the linter is never installed or run on # this builds that phase; the linter is never installed or run on
# a developer host, where a shared result cache and a host-global lock # a developer host, where a shared result cache and a host-global lock
# make its answer untrustworthy. # make its answer untrustworthy.
# #
# The phase is not the last stage in the file, so it is built only when # --target builds the lint phase and the stages it depends on, nothing
# --target names it. A new CACHEBUST value reruns every RUN step after # else. A new CACHEBUST value reruns every RUN step after
# the ARG CACHEBUST line, since a cached lint layer is a lint that did # the ARG CACHEBUST line, since a cached lint layer is a lint that did
# not run; unlike --no-cache, it keeps the layers above that line and # not run; unlike --no-cache, it keeps the layers above that line and
# the cache mounts. This relies on every stage of the Dockerfile # the cache mounts. This relies on every stage of the Dockerfile
+3 -3
View File
@@ -1,8 +1,8 @@
#!/bin/sh #!/bin/sh
# script/test: run the test suite. Testing is a phase of the Dockerfile # script/test: run the test suite. Testing is a phase of the Dockerfile
# and this builds that phase alone, on the same terms as script/lint: # and this builds that phase, on the same terms as script/lint:
# --target because a phase that is not the last stage is built only when # --target so that only the test phase and the stages it depends on are
# named, and a new CACHEBUST value because a cached test layer is a test # built, and a new CACHEBUST value because a cached test layer is a test
# that did not run; unlike --no-cache, it keeps the layers above the ARG # that did not run; unlike --no-cache, it keeps the layers above the ARG
# CACHEBUST line and the cache mounts. This relies on every stage of the # CACHEBUST line and the cache mounts. This relies on every stage of the
# Dockerfile declaring ARG CACHEBUST before every step that lints, tests # Dockerfile declaring ARG CACHEBUST before every step that lints, tests