015-comments.md

Комментарии

Комментарий — это способ передачи мысли не компьютеру, а человеку, который в будущем будет его читать и работать с ним.

Полезный комментарий объясняет, почему написан тот или иной код, а не дублирует очевидное. Комментарии должны раскрывать контекст и мотив, а не пересказывать строку кода.

// Плохо [✗]
// Устанавливаем переменную в 5
$counter = 5;

// Добавить 1 к счётчику
$counter++;

Здесь комментарии не добавляют никакой ценности — код и так очевиден. Они просто повторяют написанное и засоряют пространство, вместо того чтобы объяснить логику или замысел.

// Хорошо [✓]
// Начинаем с 5, потому что первые 5 пользователей
// уже были зарегистрированы вручную
$counter = 5;

// Увеличиваем счётчик, потому что обработан новый заказ
$counter++;

Здесь комментарии оправдывают поведение. Они отвечают на вопрос: "Почему 5?" и "Почему инкремент?" Это контекст, который не видно из самого кода. Именно в этом — ценность комментария.

Иногда комментарий вообще не нужен — достаточно хорошо подобранного имени переменной:

// Плохо [✗]
// date for yesterday
$date = date('Y-m-d', strtotime('yesterday'));

Имя переменной — это уже встроенный комментарий. Используй силу языка. Не пиши объяснений в воздухе — дай имя понятию.

// Хорошо [✓]
$yesterday = date('Y-m-d', strtotime('yesterday'));

Это намного лучше любого комментария.

Обновляйте комментарии вместе с кодом

Если вы меняете логику, обязательно обновите комментарий. Иначе он превращается в ложь, а ложь хуже полного отсутствия информации.

// Плохо [✗]
// Этот метод работает с MySQL 5.7
// поэтому не использует JSON‑функции
public function processData($data)
{
    // Код, который уже использует JSON‑функции
}

Комментарий устарел, но код остался. Теперь он вводит в заблуждение. Либо обновите комментарий, либо удалите его.

Также при выполнении срочной задачи мы заранее понимаем, что код может быть неидеальным или потребовать доработок, и тем самым как бы заранее оправдываем это через:

// TODO: временное решение, нужно переписать
// FIXME: костыль, но работает
// HACK: не очень красиво, но быстро

Вместо комментария-оправдания исправьте код. Если времени нет — создайте задачу в трекере. Или настройте инструмент автоматизации, который по ключевым словам будет создавать новые задачи.

Многострочные комментарии

Многострочные комментарии — это особый жанр. Они должны быть не просто информативными, но и визуально удобными. Чем легче комментарий воспринимается глазом, тем быстрее программист понимает код.

Часто можно встретить такой вариант:

// Плохо [✗]

/**
 * Сохраняем пользователя сразу,
 * чтобы избежать потери данных, ведь последующие
 * действия могут вызвать исключение.
 * Ранее делали событие, но было ненадёжно.
 */

Проблема здесь в том, что строки разбиты случайно: одна слишком короткая, другая — длинная. В итоге комментарий выглядит тяжело и рвано.

Гораздо лучше, чтобы каждая последующая строка была такой же длины или чуть компактнее предыдущей. Комментарий тогда превратится в лестницу, по которой глаз легко скользит вниз.

Такой приём превращает комментарий в ступеньки, по которым взгляд движется естественно:

// Хорошо [✓]

/**
 * Сохраняем пользователя сразу, чтобы избежать потери данных,
 * ведь последующие действия могут вызвать исключение.
 * Ранее делали событие, но было ненадёжно.
 */

Комментарий с примером

Комментарии в конфигурационных файлах часто страдают от излишней абстрактности. Например, разработчику нужно указать, где находятся SVG-иконки приложения:

/*
 |--------------------------------------------------------------
 | Icons Path
 |--------------------------------------------------------------
 |
 | Provide the path from your app to your SVG icons directory.
 |
 */

'icons' => [],

Возникают вопросы: каков формат массива, путь полный или относительный? Без конкретного примера разработчик вынужден угадывать или спрашивать у коллег, что приводит к дополнительному времени и несамостоятельности. Чтобы исправить ситуацию, нужно добавить пример использования:

/*
 |--------------------------------------------------------------
 | Icons Path
 |--------------------------------------------------------------
 |
 | Provide the path from your app to your SVG icons directory.
 |
 | Example: ['fa' => storage_path('app/fontawesome')]
 |
 */

'icons' => [],

Теперь комментарий не только объясняет идею, но и даёт готовую основу для настройки. Абстрактная фраза превратилась в конкретное знание, и разработчику не нужно гадать.