feat: Improved comment etiquette for the sisyphus suite
This commit is contained in:
3 files changed
+7
-5
No files matched your search
@@ -222,7 +222,8 @@ nodes:
|
||||
3. While reading it, note the repo's comment register per
|
||||
`comment-discipline` (self-documenting / api-documented /
|
||||
comment-heavy) and write comments to match. When the signal is
|
||||
weak, write NO comment.
|
||||
weak, write NO comment. Every comment must EARN ITS KEEP — if
|
||||
the code already tells the reader, don't add it.
|
||||
4. If the change touches boundaries, error paths, jobs, or state
|
||||
transitions, also note the logging register per
|
||||
`logging-discipline` (logger, message style, payload vs IDs,
|
||||
@@ -323,7 +324,8 @@ nodes:
|
||||
- Suppressed errors (as any, @ts-ignore, #[allow(...)] on unfamiliar
|
||||
lints, empty catch blocks)
|
||||
- Dishonest naming (get_X that mutates, returns wrong type, etc.)
|
||||
- Useless comments that restate the code
|
||||
- Useless comments that restate the code, or that otherwise don't earn
|
||||
their keep (the code already tells the reader)
|
||||
- AI slop (filler prose, multi-paragraph docstrings, defensive
|
||||
handling of impossible cases)
|
||||
|
||||
|
||||
Reference in new issue
Block a user