Нужны ли комментарии в коде?

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

`// Отсортируем таблицу ОтсортироватьТаблицу();

// Удалим последний элемент УдалитьПоследнийЭлемент();

Но что мы знаем об этом коде? Почему нужно отсортировать таблицу? Зачем удалять последний элемент?

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

Когда комментарии нужны?

• Для объяснения контекста. Рассказываем зачем мы это делаем.

`// Для выгрузки в файл нужно удалить последний элемент, так как в нем хранится служебная информация // Ее выгружать не требуется ОтсортироватьТаблицу(); УдалитьПоследнийЭлемент();

• При описании хитрой логики. Если в коде используются сложные алгоритмы, оптимизации или “хитрые” обходные пути, то рассказав о них в комментарии мы сэкономим время в будущем.

• Для обоснования технических решений. Например, почему использован один подход вместо другого

А что, если без комментариев?

Без комментариев, скорее всего, придется потратить больше времени на изучение чужого или даже своего кода. Разумеется, идеальный код должен быть предельно понятным и самодокументирующимся. Но в реальном мире бывают дедлайны, ошибки, технический долг — и комментарии помогают всем, кто будет работать с этим кодом после тебя.

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

Например, на картинке ниже приведено описание модуля СчетаУчетаВДокументах из БухгалтерииПредприятия. В этом комментарии объясняется как работать с этим кодом, где точки входа и на что обратить внимание. Если ты уже работал с этим кодом, то сможешь легко восстановить контекст, если не работал, то это простой способ разобраться.

👀 Как вы считаете, когда комментарии в коде оправданы?

P.S. В тему обсуждения: вот переводная статья на Хабре - Самодокументируемый код – это (как правило) чушь Никита Арипов | 1C. Подписаться``