Привет, дорогой читатель, меня зовут Ксавье Жувено, и это пятая статья о Code Craft Пита Гудлиффа. Если хотите, можете посмотреть предыдущую статью о Самодокументации, а книгу можно найти здесь.

Глава, которую мы рассмотрим сегодня, называется «Промежуточный комментарий — Как писать комментарии к коду».

Вернемся к основам — Что такое комментарий?

Комментарий — это элемент исходного кода, который не читается компилятором/интерпретатором. Его единственная цель — быть прочитанным людьми. Это на самом деле очень важно для любого программиста, чтобы понять это правильно.

КОММЕНТАРИИ ДЕЛАЮТСЯ, ЧТОБЫ БЫТЬ ПОНЯТНЫМИ И УДОБНЫМИ ДЛЯ СЛЕДУЮЩЕГО ПРОГРАММИСТА

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

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

Что мне тогда писать (и не писать) в комментарии?

Чтобы жить по заявлению, описанному в предыдущей части, при написании кода автор Code Craft дает нам в комментарии список элементов, которые нужно ставить или нет. Мотивация этого списка заключается в том, что Плохой комментарий хуже, чем его отсутствие, поскольку он вводит вас в заблуждение. Чтобы придумать этот список и пример кода, автор, должно быть, видел очень странные комментарии 😆

Разыскиваемые

Комментарии должны и должны объяснять ПОЧЕМУ код такой: почему была выбрана эта реализация, когда эту работу могла бы выполнить другая, или почему этот код существует, какова его цель.

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

Не документируйте плохой код — перепишите его, Элементы стиля программирования Брайана У. Кернигана и П. Дж. Плаугера 🙂

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

Нежелательные

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

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

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

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

Как работать с комментариями

Наконец, давайте посмотрим, как вы можете работать с комментариями по некоторым конкретным моментам. 🙂

Макет комментариев

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

Два других момента, упомянутых автором, это:

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

Комментарий как флаг

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

Автор дает три флага, которые вы можете использовать и которые часто обнаруживаются IDE, чтобы вам было легче взаимодействовать с ними:

  • Комментарий, начинающийся с XXX, указывает на трудный для понимания код.
  • Комментарий, начинающийся с FIXME, указывает на код с ошибкой.
  • Комментарий, начинающийся с TODO, чтобы указать на еще не реализованную реализацию.

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

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

Комментарий для написания алгоритма

Когда вы хотите реализовать сложный алгоритм, техника — это использование комментариев. Для этого вы пишете комментарий для каждого шага вашего алгоритма (каждый шаг может быть либо на простом английском, либо в псевдокоде). Затем под каждым шагом, под каждым комментарием вы пишете код, который делает именно то, что представляет собой шаг. Как только вы это сделаете, у вас должен быть работающий алгоритм без особых проблем. Все, что вам осталось сделать, это удалить ненужные комментарии. 😉

Вывод

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

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

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

Первоначально опубликовано на http://10xlearner.com 11 февраля 2020 г.