Комментарии в коде

#дискуссия

На днях, автор канала Cross Join опубликовал пост с рассуждениями на тему того, насколько в коде нужны комментарии.

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

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

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

Существуют разные точки зрения на комментирование кода. Автор книги "Чистый код", к примеру, призывает писать код без комментариев, объясняя это тем, что каждый оставленный комментарий - это неудача и комментировать код стоит только в крайнем случае.

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

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

А как вы подходите к написанию комментариев в коде?