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

Мой краткий комментарий о том, почему вы должны отказаться от использования комментариев в коде (за исключением особых случаев)

Tl;dr

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

Введение

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

Источник: Мемы программистов Твиттер

Это фото — лучший комментарий о добавлении комментариев к коду за всю историю. Хотелось бы сказать, что это преувеличение. Но в чем разница между приведенным выше комментарием и комментарием в функции ниже?

// function to count the perimeter of the triangle
// input: 3 numbers, output: number
const countTrianglePertimeter = (a: number, b: number, c: number)
: number => {
    return a + b + c;
}

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

Причины прекратить добавлять комментарии в код

Комментарии просто излишни в коде

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

Комментарии часто устаревают

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

Комментарии могут вводить в заблуждение

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

Комментарии делают исходный код длиннее

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

Все боятся удалять или некомментировать закомментированный код

Иногда мы оставляем код закомментированным на случай, если он пригодится в будущем. Но давайте будем честными — нет более страшной вещи, чем закомментированный код, который никто не знает зачем. Можем ли мы просто удалить его? Почему это не работает? Что произойдет, если мы его не закомментируем? Оставлять в коде закомментированные незаконченные или «почти работающие» фрагменты было полезно много лет назад. Но теперь у нас есть отличные системы версионирования кода, такие как git — удаление кода с осмысленным и описательным сообщением о фиксации (и в конечном итоге добавление тега, чтобы его было легче найти позже) гораздо удобнее, понятнее и проще для возврата. Кроме того, почти никто не начинает реализацию новой функции с поиска какого-то закомментированного кода в кодовой базе. Поэтому вероятность того, что кто-то воспользуется вашим ненужным в данный момент кодом, очень мала.

Особые случаи, когда комментарии могут быть полезны

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

Regexes

Есть старая поговорка: «Если у вас есть проблема и вы используете для ее решения регекс, то у вас две проблемы». Регулярные выражения великолепны и полезны, но, к сожалению, не очень читабельны. Поэтому добавление комментариев, объясняющих, что именно проверяет данное регулярное выражение, — не самая плохая идея.

Специфическая бизнес-логика

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

Комментарии TODO

Процесс разработки разбит на этапы. И вполне нормально не включать все изменения в один коммит, а оставить их для следующих. Когда ваш проект небольшой и вы не используете никаких инструментов для отслеживания задач (например, Jira или Github Issues), наличие TODO-комментариев, указывающих, что и где должно быть изменено, может быть полезным. Особенно потому, что редакторы кода имеют специальные механизмы для их поддержки. Проблема здесь в том, что это решение не масштабируется и может быть неэффективным для больших проектов.

Советы о комментариях и их избегании

Некоторые советы могут помочь вам решить, нужны ли комментарии и как правильно их использовать. Прежде всего, перед написанием комментария подумайте, можете ли вы представить то же содержание в коде. Зачем вам нужен свободный текст, чтобы выразить свое намерение? Почему код не может говорить сам? Очень часто необходимость написания комментария является лишь симптомом необходимости рефакторинга. Кроме того, если вы вынуждены написать комментарий (по одной из причин, описанных в предыдущем разделе), держите комментарий как можно ближе к коду, который он описывает. Если вы добавите свои мысли в начало файла, человек, читающий код, скорее всего, не заметит их или не обновит их при реализации некоторых изменений. И говоря об изменениях — не отслеживайте их в исходном коде. Git, безусловно, лучшее место для отслеживания изменений и их авторов. Кроме того, git (или любая другая система версий) — ваш друг, если вы хотите удалить какую-то функциональность, но у вас есть шанс вернуть ее. Не комментируйте исходный код — вместо этого создайте коммит с осмысленным именем, и программисты найдут его в истории, если понадобится. Благодаря всем этим советам ваш код станет чище, актуальнее и читабельнее для всех.

Резюме

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