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-18 17:03:04 +02:00
parent a53b54039b
commit 47fa9dbe96
2 changed files with 13 additions and 13 deletions
Download patch file Download diff file Expand all files Collapse all files

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

@ -1,12 +1,12 @@
## JS/Go Code Comment Rules
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.
- Keep comments **compact** and default to one line for "what" in the format `// Name does X.`. Skip trivial getters (`isOpen: () => this.open`).
- Add 1-2 follow-up lines (`// …`) **only** if 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 infer the "why" from the function body or a nearby line, then omit it.
- Multi-paragraph explanations belong in `specs/`, package `README.md` files, or GitHub issues — never in the source itself.
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.
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. For short examples in comments, indent code instead of using backticks.
Use US English spelling in all code comments (`parameterized`, `behavior`, `color`, `serialize`, `normalize`, `optimize`, …) — not the British `-ised`/`-our`/`-re` variants.
> **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.

14
AGENTS.md
View file

@ -108,14 +108,14 @@ Title Case rules (Chicago-style, with code- and path-aware normalization):
### JS/Go Code Comments
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.
- Keep comments **compact** and default to one line for "what" in the format `// Name does X.`. Skip trivial getters (`isOpen: () => this.open`).
- Add 1-2 follow-up lines (`// …`) **only** if 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 infer the "why" from the function body or a nearby line, then omit it.
- Multi-paragraph explanations belong in `specs/`, package `README.md` files, or GitHub issues — never in the source itself.
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. For short examples in comments, indent code instead of using backticks.
Use US English spelling in all code comments (`parameterized`, `behavior`, `color`, `serialize`, `normalize`, `optimize`, …) — not the British `-ised`/`-our`/`-re` variants.
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