Как комментарии могут прояснить то, что код не может

«Как добавлять комментарии к коду» - это… напряженная тема. Это не совсем то, что «табуляция против пробелов», но это близко. Некоторые инженеры воспринимают простое присутствие комментариев как признак плохого кода. Я думаю, что это немного сурово, так что давайте вступим в войну пламени и поговорим о том, что является хорошим комментарием и как его написать.

Что и почему

Обычно комментарии критикуют за то, что они излишни:

// add students to honor roll if they have a high grade
students.forEach(student => {
  if (student.grade > honorRoll) {
    honorRollStudents.push(student) 
  }
}

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

Разочаровывающий пример из реального мира

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

if (user.default_name) delete user.default_name;
await Database.User.migrate(user);

Почему мы удаляем default_name? Нашим первым инстинктом было поискать в репо другие экземпляры default_name, но мы их не нашли. Мы спрашиваем нашу команду, но никто не знает, и парень, который это написал, ушел. Это просто потому, что сейчас мы используем более новое поле username? Мы вынуждены зайти в Slack и спросить, не пользуется ли им кто-нибудь. Оказывается, у группы подписок есть устаревшая система, которая использует default_name существование, чтобы определить, принадлежит ли пользователь v1 или v2. Поскольку мы переходим на v2, мы удаляем это поле.

Добавление объяснения

Теперь, когда мы знаем, зачем мы это делаем, мы можем поместить это в функцию с описательным именем:

const makeSureUserAppearsNewToSubscriptionAPI = (user) => {

Но это громоздко. Комментарий был бы идеальным:

// subscription API needs this to be null for v2 users
if (user.default_name) delete user.default_name;

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

"Это плохой код"

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

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

Меньше - больше

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

Держите их короткими

Комментарии противоречивы, поэтому чем короче, тем лучше:

// we need this to set up the user's permissions for v3 auth method
# should be
// set user permissions for updated v3 auth

Более длинные комментарии должны быть отформатированы

Если вам нужно более одной строки, попробуйте разбить запутанный фрагмент кода на функцию, а затем добавить комментарий в стиле jsDoc:

/**
 * To support a 3rd party integration we must
 * ping their servers and wait for OK signal
 * @param {object} user - user data sent after OK
 */
const createViaIntegration = (user) => {

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

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

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

В заключение

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

счастливого кодирования всех,

Майк