a57fac7a78
* docs: add code comment guidelines to AGENTS.md Co-Authored-By: eunjae@cal.com <hey@eunjae.dev> * docs: extract comment guidelines into agents/rules and reference from AGENTS.md Co-Authored-By: eunjae@cal.com <hey@eunjae.dev> --------- Co-authored-by: Devin AI <158243242+devin-ai-integration[bot]@users.noreply.github.com>
52 lines
1.5 KiB
Markdown
52 lines
1.5 KiB
Markdown
---
|
|
title: Code Comment Guidelines
|
|
impact: MEDIUM
|
|
impactDescription: Excessive comments add noise; missing comments hurt maintainability
|
|
tags: comments, documentation, readability
|
|
---
|
|
|
|
# Code Comment Guidelines
|
|
|
|
## General Principle
|
|
|
|
Keep comments limited and avoid obvious ones. Comments should explain "why" not "what" - the code itself should be clear enough to explain what it does.
|
|
|
|
## When to Comment
|
|
|
|
- Business decisions or domain logic that isn't obvious from the code
|
|
- Workarounds or hacks with explanation of why they're needed
|
|
- Non-obvious performance optimizations
|
|
- Important security considerations
|
|
- Troubleshooting context (e.g., why a particular approach was chosen after hitting issues)
|
|
|
|
If none of these apply, skip the comment entirely. The function name, parameters, and return type should speak for themselves.
|
|
|
|
## When NOT to Comment
|
|
|
|
```typescript
|
|
// ❌ Bad - Obvious comment
|
|
// Get the user
|
|
const user = await getUser(userId);
|
|
|
|
// ❌ Bad - Restating the code
|
|
// Loop through bookings
|
|
for (const booking of bookings) {
|
|
// Process booking
|
|
processBooking(booking);
|
|
}
|
|
```
|
|
|
|
## Good Examples
|
|
|
|
```typescript
|
|
// ✅ Good - Explains why, not what
|
|
// We need to fetch availability before slots because the timezone
|
|
// conversion depends on the user's configured availability rules
|
|
const availability = await getAvailability(userId);
|
|
const slots = convertToSlots(availability, timezone);
|
|
|
|
// ✅ Good - Documents a non-obvious constraint
|
|
// Google Calendar API has a 2500 event limit per sync request
|
|
const BATCH_SIZE = 2500;
|
|
```
|