You signed in with another tab or window. Reload to refresh your session.You signed out in another tab or window. Reload to refresh your session.You switched accounts on another tab or window. Reload to refresh your session.Dismiss alert
Comments should explain *why* the code exists, not what it does. Well-named identifiers already say what the code does, so a comment that only restates the code is dead weight.
11
+
12
+
### Incorrect
13
+
14
+
```tsx
15
+
// loop through users
16
+
users.forEach(processUser);
17
+
```
18
+
19
+
### Correct
20
+
21
+
```tsx
22
+
// We only include active users to avoid reprocessing deactivated ones
23
+
users.forEach(processUser);
24
+
```
25
+
26
+
---
27
+
28
+
### Review Metadata
29
+
30
+
Flag ONLY when BOTH of these are true:
31
+
32
+
- The changed code adds or modifies a comment
33
+
- The comment restates what the code does instead of explaining why it exists
34
+
35
+
**DO NOT flag if:**
36
+
37
+
- The comment is a JSDoc `@param` or `@returns` description, where stating what the parameter or return value is is the expected content, not a why explanation
38
+
- Stating what the code does is genuinely the only way to orient a reader, such as documenting a regex or a bit-flag mask
39
+
40
+
**Search Patterns** (hints for reviewers):
41
+
- Any newly added or modified `//` or `/* */` comment that only restates the code below it
## [CONSISTENCY-16] Write comments as plain, natural sentences
7
+
8
+
### Reasoning
9
+
10
+
Comments should read like something a person actually wrote: plain sentences without the stylistic tics that make prose harder to read, such as em dashes, redundant parentheticals, stacked hyphenated modifiers, arrows, semicolons, and trailing placement on the same line as the code.
11
+
12
+
### Incorrect
13
+
14
+
```tsx
15
+
doThing(); // cache the result
16
+
17
+
// Set the pendingAction to ADD — this exercises the optimistic-update branch before the API responds
18
+
19
+
// When the assigned guide (who is not a policy admin) comments, then it succeeds
20
+
21
+
// the not-yet-validated user-supplied bank-account number
22
+
23
+
// persisted -> processing transition
24
+
25
+
// retry once; the token had expired
26
+
```
27
+
28
+
### Correct
29
+
30
+
```tsx
31
+
// Cache the result to avoid reading from the database every time
32
+
doThing();
33
+
34
+
// Set the pendingAction to ADD to go through the optimistic-update branch before the API responds
35
+
36
+
// The assigned guide isn't a policy admin, but the comment still succeeds
37
+
38
+
// The bank account number the user supplied, before validation
39
+
40
+
// SequentialQueue moves the request from persisted to processing
41
+
42
+
// Retry once because the token had expired
43
+
```
44
+
45
+
---
46
+
47
+
### Review Metadata
48
+
49
+
Flag ONLY when BOTH of these are true:
50
+
51
+
- The changed code adds or modifies a comment
52
+
- In its own sentence, not inside a quoted code snippet or string literal it's documenting, the comment does at least one of the following:
53
+
- Uses an em dash or en dash
54
+
- Uses a redundant parenthetical that just repeats what the surrounding sentence already says
55
+
- Stacks more than one hyphenated compound modifier in front of a noun
56
+
- Uses `->` instead of writing the relationship in words
57
+
- Uses a semicolon instead of two separate sentences
58
+
- Trails at the end of a code line instead of sitting on its own line directly above it
59
+
60
+
**DO NOT flag if:**
61
+
62
+
- The dash, arrow, or semicolon appears inside a quoted code example, string literal, or file path the comment is documenting, rather than in the comment's own sentence
63
+
- A single, ordinary compound modifier like "well-known" or "high-risk" is used. Only a stacked chain of several modifiers in front of one noun is a violation
64
+
65
+
**Search Patterns** (hints for reviewers):
66
+
- Any newly added or modified `//` or `/* */` comment
0 commit comments