quality-code-comments.md

---

title: Only Add Comments That Explain Why impact: MEDIUM impactDescription: Reduces noise and keeps codebase clean tags: quality, comments, documentation

Паспорт документа

• Статус документа: living standard
• Актуально на: 28 марта 2026 года
• Владелец: backend/platform-команда
• Пересмотр: при изменении инженерной практики, CI/CD, архитектурных правил или локального workflow
• Область применения: внутренние rule/reference-card документы для инженерной команды
• Связанные документы:
  • Индекс Agents
  • Команды разработки
  • Инженерные принципы

Only Add Comments That Explain Why

Impact: MEDIUM

Comments should explain why something is done, not what the code does. Well-named functions and variables should make the "what" obvious.

Incorrect (restating the code):

// Get the item by slug
const item = await this.itemRepo.findBySlug(slug);

// Check if item exists
if (!item) {
  // Throw not found error
  throw new NotFoundException();
}

// Return the item
return item;

Correct (explaining the why):

const item = await this.itemRepo.findBySlug(slug);
if (!item) throw new NotFoundException();

// Cache invalidation happens here because sellers can update
// item data at any time, and stale cache causes price mismatches
await this.cacheService.invalidate(`item:${slug}`);

return course;

When to add comments:

• Business rule explanations ("We cap at 5 because...")
• Workarounds for known issues ("Prisma doesn't support X, so we...")
• Non-obvious performance choices ("Using Map instead of filter to avoid O(n^2)")
• TODO markers for known tech debt (// TODO: replace with Elasticsearch when ready)