---
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](../README.md)
  - [Команды разработки](../commands.md)
  - [Инженерные принципы](../../governance/engineering-principles.md)

## 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):**

```typescript
// 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):**

```typescript
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`)