Mirrors/photoprism
1
0
Fork 0
mirror of https://github.com/photoprism/photoprism.git synced 2026-07-17 16:49:04 +00:00
Code Issues Projects Releases Wiki Activity

Rules: Update shared code comment writing rules

Browse source 
Signed-off-by: Michael Mayer <michael@photoprism.app>
This commit is contained in:
Michael Mayer 2026-05-17 15:42:31 +02:00
parent d5649e1309
commit 5ada2aa40a
2 changed files with 6 additions and 4 deletions
Download patch file Download diff file Expand all files Collapse all files

5
.claude/rules/code-comments.md
View file

@ -1,11 +1,12 @@
## JS/Go Code Comment Rules
Doc comments for packages and exported identifiers must be complete sentences that begin with the name of the thing being described and end with a period.
A doc comment is **required** for every function (including unexported helpers), as well as for every non-trivial Vue `methods:` / `computed:` / watcher:
- Keep comments **compact** and default to one line for WHAT in the format `// Name does X.`. Skip trivial getters (`isOpen: () => this.open`).
- Add up to three follow-up lines (`// …`) only when the WHY is non-obvious: a hidden invariant, a workaround that would otherwise be undone by a future cleanup, a contract a reader can't infer from the code.
- If readers can derive the WHY from the function body or a nearby line, leave it out. Multi-paragraph explanations belong in `specs/`, package `README.md` files, or GitHub issues — never in the source itself.
- For short examples in comments, indent code instead of using backticks.
Doc comments for packages and exported identifiers must be complete sentences that begin with the name of the thing being described and end with a period.
Use US English spelling in all code comments (`parameterized`, `behavior`, `color`, `serialize`, `normalize`, `optimize`, …) — not the British `-ised`/`-our`/`-re` variants. Identifiers in code that already use a different spelling (e.g. an existing exported symbol) are not in scope; only the prose in comments and doc strings.
> **Don't include in code comments:** Issue / PR numbers, "previously…" history, alternatives considered, what the function used to do, references to old commits, names of subsequent reviewers, or any narrative that names the change rather than the steady-state behavior. That context belongs in commit messages, specs, or handover notes.

5
AGENTS.md
View file

@ -107,14 +107,15 @@ Title Case rules (Chicago-style, with code- and path-aware normalization):
### JS/Go Code Comments
Doc comments for packages and exported identifiers must be complete sentences that begin with the name of the thing being described and end with a period.
A doc comment is **required** for every function (including unexported helpers), as well as for every non-trivial Vue `methods:` / `computed:` / watcher:
- Keep comments **compact** and default to one line for WHAT in the format `// Name does X.`. Skip trivial getters (`isOpen: () => this.open`).
- Add up to three follow-up lines (`// …`) only when the WHY is non-obvious: a hidden invariant, a workaround that would otherwise be undone by a future cleanup, a contract a reader can't infer from the code.
- If readers can derive the WHY from the function body or a nearby line, leave it out. Multi-paragraph explanations belong in `specs/`, package `README.md` files, or GitHub issues — never in the source itself.
- For short examples in comments, indent code instead of using backticks.
Doc comments for packages and exported identifiers must be complete sentences that begin with the name of the thing being described and end with a period.
Use US English spelling in all code comments (`parameterized`, `behavior`, `color`, `serialize`, `normalize`, `optimize`, …) — not the British `-ised`/`-our`/`-re` variants. Identifiers in code that already use a different spelling (e.g. an existing exported symbol) are not in scope; only the prose in comments and doc strings.
> **Don't include in code comments:** Issue / PR numbers, "previously…" history, alternatives considered, what the function used to do, references to old commits, names of subsequent reviewers, or any narrative that names the change rather than the steady-state behavior. That context belongs in commit messages, specs, or handover notes.
## Agent Runtime