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

Как правильно писать комментарии к коду: несколько важных примеров

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

Читайте также: Как читать чужой код: 6 правил, которые стоит помнить разработчику

#FIXME

Тег #FIXME показывает, что в этой части кода нужно что-то исправить. В некоторых случаях функциональность этого тега сливается с #TODO , поэтому #FIXME рекомендуется использовать, когда нужно указать на участок кода, от которого в будущем могут потенциально возникать проблемы.

#Warning

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

#Error

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

Как правильно применять теги

В каждой основной IDE есть плагины для работы с комментариями и их группировки. Например, в VS Code самый распространенный способ работы с такими комментариями — плагин Todo Tree, создающий дерево из групп комментариев для эффективной работы с ними.

В IDE от JetBrains комментарии #TODO и #FIXME автоматически определяются средой разработки в единые группы тегов. Подробнее об этом и том, как можно расширить функционал этой фичи на другие пользовательские комментарии, можно почитать на сайте JetBrains.

Напишите свое лучшее резюме У нас есть сервис Хекслет CV, где любой разработчик может опубликовать свое резюме и получить бесплатные комментарии от других программистов и HR-менеджеров, как его улучшить и что добавить к рекомендательному письму.

Лучшие практики написания комментариев к коду

Известный профессор МТИ Гарольд Абельсон сказал: «Программы нужно писать для того, чтобы их читали люди, и лишь случайно — чтобы их исполняли машины». Хотя он намеренно преуменьшил важность исполнения кода, однако подчёркивает, что у программ две важные аудитории. Компиляторы и интерпретаторы игнорируют комментарии и с одинаковой лёгкостью воспринимают все синтаксически корректные программы. У людей всё иначе. Одни программы нам воспринимать легче, чем другие, и мы ищем комментарии, которые помогут нам разобраться.

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

Как писал Питер Фогель:

1. Написание и поддержка комментариев требует усилий.
2. Ваш компилятор не смотрит на комментарии, поэтому невозможно определить их корректность.
3. С другой стороны, вы гарантируете, что компьютер делает именно то, что предписывает ваш код.

Первое правило: комментарии не должны дублировать код

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

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

Неинформативные комментарии вредны, потому что:

• вносят визуальный беспорядок;
• отнимают время на написание и чтение;
• могут устареть.

Комментарий не добавляет полезной информации и требует усилий по поддержке.

Требования комментировать каждую строку справедливо высмеяли на Reddit:

Второе правило: хорошие комментарии не оправдывают непонятный код

Ещё один способ некорректного использования комментариев — предоставление информации, которая должна содержаться в коде. Например, когда кто-то назвал переменную одной буквой и добавил комментарий с объяснением:

Комментарий был бы не нужен, если дать переменной правильное название:

Как написали Керниган и Плогер в книге «The Elements of Programming Style»: «Не комментируйте плохой код, а переписывайте его».

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

Самый известный комментарий в исходном коде Unix звучит так: «Вряд ли вы это поймёте». Его вставили перед запутанным кодом переключения контекста. Дэннис Ричи позднее объяснил, что это был не наглый вызов, а высказывание в духе «На экзамене такого не будет». Но похоже, что он сам и его соавтор Кен Томпсон сами не поняли свой код, и позднее переписали его. Всё это напоминает о законе Кернигана:

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

Четвёртое правило: комментарии должны исключать путаницу, а не вносить её

Ни одно обсуждение плохих комментариев нельзя считать полным без этой истории из «Hackers: Heroes of the Computer Revolution» Стивена Леви:

Хотя я ценю хороший хак, но это не пример для подражания. Если ваш комментарий вносит путаницу, а не устраняет, то удалите его.

Пятое правило: объясняйте в комментариях не идиоматический код

Лучше комментировать код, который кто-нибудь может счесть ненужным или избыточным, вроде этого кода из App Inventor (источника всех моих положительных примеров):

Без комментария кто-нибудь может «упростить» код или счесть его таинственным, но необходимым заклинанием. Сэкономьте время и нервы будущих читателей и напишите, для чего нужен этот код. Необходимо оценивать, нуждается ли код в объяснении. Когда я изучал Kotlin, я столкнулся в руководстве по Android с подобным кодом:

Я удивился, почему бы не заменить его просто на if (b) , как сделал бы это на Java. В результате небольшого исследования я выяснил, что допускающие пустое значение булевы переменные явным образом сравниваются с true, чтобы избежать уродливой проверки на null:

Я рекомендую не добавлять комментарии к распространённым идиомам, если только вы не пишете руководство для новичков.

Шестое правило: добавляйте ссылки на исходный код, который вы скопировали.

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

• какую задачу вы решали;
• кто предоставил код;
• почему это решение рекомендовано;
• что думали об этом комментаторы;
• работает ли это ещё;
• как его можно улучшить.

Если перейти по ссылке, то вы обнаружите, что:

• Автора кода зовут Tomáš Procházka, он входит в топ-3% на Stack Overflow.
• Один из комментаторов предложил улучшение, уже внесённое в репозиторий.
• Другой комментатор предложил способ избежать пограничного случая.

Любой, кто захочет разобраться в коде, вынужден будет искать эту формулу. А если бы вставили ссылку, то можно было бы гораздо быстрее найти источник.

Некоторые программисты могут не захотеть указывать, что они не сами написали код, но повторное использование кода может быть разумным шагом, экономящим время и дающим вам преимущество в виде большего количества проверяющих. Конечно, никогда не вставляйте код, который не понимаете. Люди копируют со StackOverflow много кода, который попадает под лицензирование Creative Commons, требующее указания авторства. Для этого достаточно указать ссылку на первоисточник.

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

Седьмое правило: добавляйте ссылки на внешние примеры в тех случаях, когда это полезнее всего

Конечно, не все ссылки ведут на Stack Overflow.

Ссылки на стандарты и другую документацию помогут читателям понять проблему, которую решает ваш код. Хотя эта информация может храниться в проектной документации, однако удачно размещённый комментарий станет своевременным указателем. В приведённом примере ссылка подсказывает, что RFC 4180 обновили на RFC 7111, это полезная информация.

Восьмое правило: исправляя баги, добавляйте комментарии

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

Комментарий не только помогает понять код в конкретных методах, но и определить, нужен ли ещё этот код и как его тестировать. Также комментарий может ссылаться на систему отслеживания ошибок:

Конечно, можно с помощью git blame найти коммит, в котором была добавлена или изменена строка. Однако пояснения к коммитам обычно краткие, и самые важные изменения (например, исправление бага №1425) могут не содержаться в последнем коммите (который, скажем, переместил метод из одного файла в другой).

Девятое правило: помечайте комментариями незаконченные реализации

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

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

Неужели комментировать код — это плохо?

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

Какой в нем смысл?

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

Нужны доказательства? Возьмем вот этот код без комментариев:

Этот блок кода выполняет несколько функций. Результат: программисты не могут быстро понять, что же именно делает данный код.

А теперь снабдим тот же код комментариями.

Разве читабельность кода не возросла? Все потому, что комментарии описывают то, что делает код, в то время, как сам код показывает, как это делается.

Мы же, разработчики, привыкли мыслить критериями «что», забывая про «как».

Так, получается, что комментарии объясняют наш код?

Звучит не плохо …

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

Почему же комментирование стало «самым худшим»?

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

Так почему бы не завести блог с названием «Пожалуйста, читайте комментарии»?

Хороший вопрос! Потому что нельзя верить комментариям, которые вы читаете.

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

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

Конечно же, нет, это часто забывается.

Вот именно. Так что делайте так, чтобы в ваших системах присутствовал лишь один источник истины.

Хорошо, признаю, комментарии — это не самое правильное решение. Но ничто не идеально в этом мире. Так вы говорите, что есть вариант получше?

Да. Покажите мне ваш комментарий, и я предложу вариант получше.

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

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

Такой принцип применим и к функциям, не так ли?

Да. Присвойте функциям и параметрам имена на основании их назначения. Как только это сделано, необходимость в комментировании стиля заголовка функции отпадет сразу.

А что насчет предыдущего кода? Там комментарии описывали блоки кода, совместно обеспечивающие его функциональность? Одно именование нам явно не поможет, разве нет?

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

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

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

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

А вдруг мне придется хорошенько потрудиться над оптимизацией какого-то кода. Можно ли тогда обратиться к комментариям?

Стоп… что?

Мы — разработчики программных продуктов. И у всех разработчиков есть инструменты. Комментарии — это те же самые инструменты, что и функции с именами переменных. Но ни одно средство не решает все проблемы сразу. И одного инструмента всегда мало. Если изменение структуры кода не улучшает его читабельность, то стоит вспомнить про комментарии.

Так комментарии — это хорошо?

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

· неправильное именование переменных или функций.

· сложность или длину кода.

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

Комментирование кода: хорошие, плохие и отвратительные комментарии

«Хороший код — это самодокументируемый код». Вы слышали эту фразу раньше? Я тоже. Более чем за 20 лет написания кода я слышал эту фразу чаще других. Это уже клише.

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

В этой статье мы рассмотрим хорошие, плохие и отвратительные примеры комментирования в коде.

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

Документационные комментарии

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

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

Посмотрите на пример кода из Lodash — популярной библиотеки для JavaScript:

Если вы сравните эти комментарии с онлайн-документацией, то увидите, что они одинаковы. При написании документационных комментариев убедитесь, что они соответствуют общепринятому стандарту и что они отличаются от уточняющих и поясняющих комментариев в самом коде. Некоторые популярные инструменты и стандарты включают использование JSDoc для JavaScript, DocFx для .Net и JavaDoc для Java.

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

Поясняющие комментарии

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

Зачастую уточняющий комментарий к вашему коду является его отражением. По пояснению можно судить нагружен ваш код или нет. Следует пытаться удалять пояснения в коде, упрощая его, ведь «хороший код — самодокументированный код».

Приведу пример плохого, но забавного пояснения:

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

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

Вам действительно хочется приукрасить рифмой свой плохой код, чтобы кодеры ухмыльнулись и проигнорировали его, двигаясь дальше?

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

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

Обычно это происходит, когда вам нужно добавить контекст к неинтуитивному решению.
Вот хороший пример из фреймворка Lodash:

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

А иногда тем самым «более умным» кодером можете оказаться вы сами. Поэтому в таких случаях лучше оставлять комментарии к коду, чтобы в будущем сэкономить своё и чужое время и нервы.

Комментарий снизу полностью отражает суть мысли выше:

Опять же, комментарий сверху содержит больше юмора, чем пользы. Вам СЛЕДУЕТ оставлять комментарии, предупреждающие других от поиска какого-либо «лучшего решения», если вы сами уже пытались это сделать, но ничего хорошего из этого не вышло. В комментарии следует указать, какое решение вы пытались найти и почему вы решили, что оно не подходит в данной ситуации или не работает.

Отвратительные комментарии

Мы уже узнали, что такое хорошие и плохие комментарии к коду. Теперь пришло время ознакомиться с отвратительными комментариями.

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

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

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

Уважайте себя и других разработчиков и не допускайте подобных комментариев в своём коде.