Как лучше писать комментарии?

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

Эта статья познакомит вас с профессиональным советом, который я прочитал в книге Чистый код.

Как следует из названия статьи:

«Не комментируйте плохой код — перепишите его». - Брайан В. Керниган и П. Дж. Плаугер

Комментарии не являются «чисто хорошими». Если код плохой, его следует отрефакторить, а не добавлять беспорядочные комментарии, чтобы сделать его еще более беспорядочным.

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

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

Но в некоторых случаях самого кода недостаточно, чтобы объяснить его поведение. Затем вам нужно добавить небольшое количество комментариев. Итак, что такое хорошие комментарии и что такое плохие комментарии?

Здесь я цитирую точку зрения автора в книге и делаю соответствующие удаления и изменения в соответствии с моим пониманием:

Хорошие комментарии

  • Юридические комментарии к тем спецификациям балансовой единицы, которые требуют написания.
  • Комментарии, предоставляющие основную информацию. Но это можно заменить понятными именами функций.
  • Комментарии, выражающие намерение. Это потому, что код уже все объясняет.
  • Уточнение: переведите значение какого-то неясного аргумента или возвращаемого значения во что-то удобочитаемое.
  • Предупреждение о последствиях. Комментарии используются для предупреждения других программистов о том, что могут возникнуть определенные последствия.
  • Комментарий TODO: Это работа, которую нужно сделать, но по какой-то причине она еще не сделана. Но это не причина оставлять плохой код.
  • Усиление: комментарии могут использоваться для усиления важности того, что в противном случае может показаться несущественным.
  • Javadocs в публичных API: информативные комментарии для быстрой разработки другими.

Плохие комментарии

  • Бормоча: Добавьте комментарии к реализации кода. Но если вы собираетесь писать, необходимо уделить время написанию наилучших возможных комментариев.
  • Излишние комментарии: не более информативны, чем сам код, и даже не длиннее, чем чтение кода.
  • Вводящие в заблуждение комментарии. Неточные комментарии вводят читателя в заблуждение и требуют дополнительных усилий.
  • Обязательные комментарии: Javadocs для каждой функции или пояснительные комментарии для каждой переменной. Это может сделать код более разрозненным.
  • Комментарии к журналу: журнал, в котором фиксируются все изменения в коде. Это бесполезно при использовании инструментов управления исходным кодом, таких как Git.
  • Маркеры положения: поместите конкретную функцию под длинной бесполезной строкой косых черт.
  • Авторство и авторство: инструменты управления исходным кодом уже записали для нас эту информацию, пожалуйста, не добавляйте ее.
  • Закомментированный код: эти закомментированные бесполезные коды заставят других читателей подумать, что должна быть причина, по которой он существует и не может быть удален. Так их наваливается все больше и больше, и только оригинальные разработчики знают для чего они нужны. Не комментируйте бесполезный код, пожалуйста, удалите его напрямую. Поскольку инструмент управления исходным кодом поможет нам записать все это, его очень легко отследить.
  • HTML-комментарии: HTML в комментариях к исходному коду — это мерзость, затрудняющая чтение.
  • Нелокальная информация: если вы должны написать комментарий, убедитесь, что он описывает код, рядом с которым он появляется.
  • Слишком много информации: не добавляйте в комментарии интересные исторические дискуссии или не относящиеся к делу подробности.
  • Неочевидная связь: связь между комментарием и кодом, который он описывает, должна быть очевидной.
  • Заголовки функций. Короткие функции не нуждаются в подробном описании. Хорошо подобранное имя для небольшой функции, которая выполняет одну задачу, обычно лучше, чем заголовок комментария.
  • Javadocs в непубличном коде: как бы ни были полезны Javadocs для общедоступных API, они являются анафемой для кода, который не предназначен для публичного использования. Генерация страниц Javadocs для классов и функций внутри системы, как правило, бесполезна, а дополнительная формальность комментариев Javadocs представляет собой не более чем бесполезность и отвлечение внимания.

Заключение

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

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

Так что ты думаешь? Как вы справляетесь с этим на работе?

Рекомендации

[1] Чистый код

На сегодня все. Меня зовут Закари, и я буду продолжать публиковать истории, связанные с веб-разработкой. Если вам нравятся такие истории и вы хотите поддержать меня, пожалуйста, подумайте о том, чтобы стать участником Medium. Это стоит 5 долларов в месяц и дает вам неограниченный доступ к контенту Medium. Я получу небольшую комиссию, если вы зарегистрируетесь по моей ссылке.

Ваша поддержка очень важна для меня — спасибо.