35 lines
1001 B
Plaintext
35 lines
1001 B
Plaintext
---
|
|
alwaysApply: true
|
|
---
|
|
|
|
# Comment Guidelines
|
|
|
|
## Good Comments (Human-style)
|
|
- Explain WHY, not WHAT
|
|
- Document non-obvious behavior or edge cases
|
|
- Warn about performance implications or side effects
|
|
- Explain business logic that isn't clear from code
|
|
|
|
Examples:
|
|
```javascript
|
|
// transfer, not copy; sender buffer detaches
|
|
// satisfies: check shape; keep literals
|
|
// keep multibyte across chunks
|
|
// timingSafeEqual throws on length mismatch
|
|
```
|
|
|
|
## Bad Comments (AI-style)
|
|
- Don't explain what the code literally does
|
|
- Don't add changelog-style comments in code
|
|
- Don't comment every line or obvious operations
|
|
|
|
Avoid:
|
|
```javascript
|
|
// Prevent duplicate initialization
|
|
// Check if project is already loaded
|
|
// Mark as initializing to prevent race conditions
|
|
// (changed from blah to blah)
|
|
```
|
|
|
|
## Rule
|
|
Only add comments when there's genuinely non-obvious behavior, performance considerations, or business logic that needs context. Code should be self-documenting through naming and structure. |