# 13. Комментирование и документация
[← Оглавление](./index.md)
---
## Код должен быть самодокументированным
Комментарии объясняют *«почему»*, а не *«что»*. Используйте выразительные имена.
**ПЛОХО — КОММЕНТАРИЙ ОПИСЫВАЕТ ОЧЕВИДНОЕ**
```php
// умножаем цену на количество
$sum = $price * $qty;
```
**ХОРОШО — ИМЯ ГОВОРИТ САМО ЗА СЕБЯ, КОММЕНТАРИЙ ОБЪЯСНЯЕТ БИЗНЕС-ПРАВИЛО**
```php
$totalPrice = $product->getPrice() * $product->getQuantity();
// Скидка для VIP-клиентов введена с Q1 2026 (см. задачу 1234)
if ($client->isVip()) {
$totalPrice *= (1 - self::VIP_DISCOUNT_RATE);
}
```
---
## PHPDoc для публичных API
**ПЛОХО — НЕТ ДОКУМЕНТАЦИИ, НЕЯСНЫ ТИПЫ И ИСКЛЮЧЕНИЯ**
```php
public function find($id) {
// ...
}
```
**ХОРОШО — ПОЛНЫЙ PHPDOC**
```php
/**
* Находит сделку по идентификатору.
*
* @param positive-int $id Идентификатор сделки в CRM
* @return \Bitrix\Crm\Item
*
* @throws \Bitrix\Main\ObjectNotFoundException если сделка не найдена
* @throws \Bitrix\Main\SystemException при ошибке базы данных
*/
public function find(int $id): \Bitrix\Crm\Item { /* ... */ }
```