Compare commits
6
Commits
| Author | SHA1 | Date | |
|---|---|---|---|
|
|
9cc6d43c68 | ||
|
|
69d38ba6de | ||
|
|
198b896a53 | ||
|
|
11245b85ca | ||
|
|
02632a5682 | ||
|
|
fdf517a1f7 |
No files matched your search
@@ -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
|
||||||
@@ -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,
|
||||||
|
|||||||
@@ -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
|
||||||
|
|||||||
@@ -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
@@ -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
@@ -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
|
||||||
|
|||||||
Reference in new issue
Block a user