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 comment-rules for multi-paragraph descriptions

Browse source 
Signed-off-by: Michael Mayer <michael@photoprism.app>
This commit is contained in:
Michael Mayer 2026-05-17 11:25:05 +02:00
parent 6ec45db03b
commit de3f1d134d
2 changed files with 2 additions and 2 deletions
Download patch file Download diff file Expand all files Collapse all files

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

@ -5,7 +5,7 @@ Doc comments for packages and exported identifiers must be complete sentences th
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 comments belong in `specs/`, package `README.md` files, or issue descriptions — never in the source itself.
- If readers can derive the WHY from the function body or a nearby line, leave it out. Multi-paragraph descriptions 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.
> **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.

2
AGENTS.md
View file

@ -111,7 +111,7 @@ Doc comments for packages and exported identifiers must be complete sentences th
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 comments belong in `specs/`, package `README.md` files, or issue descriptions — never in the source itself.
- If readers can derive the WHY from the function body or a nearby line, leave it out. Multi-paragraph descriptions 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.
> **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.