Использование комментариев в JavaScript

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

Чтобы написать комментарий в коде достаточно в начале строки добавить два слеша или заключить контент в специальные мультистрочные конструкции:

// Просто комментарий
/*
мультистрочный
комментарий
*/

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

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

// извлечь имена из БД
function names() { }

// или так
function getNames() { }

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

Однострочные и строчные комментарии

// однострочный комментарий
console.log('trig')
const name = 'trig' // строчный комментарий

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

// создание клиентских настроек
function getCustomerID();
function checkoutCustomerItems();
function createPolicy();
const num = `${id}_${policy number}`; // ID пользователя должен начинаться с цифр

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

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

Блок комментариев

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

// я - большой блок текста
// мне нужно 3 строки, чтобы объяснить
// мою цель.

Вместо этого мы должны использовать следующий вариант:

/*
я - большой блок текста
мне нужно 3 строки, чтобы объяснить
мою цель.
*/

Блочный комментарий как у профи

Отлично! На этом все скучные вопросы закончены, так что давайте посмотрим, как мы можем лучше использовать эти комментарии. Первым шагом является простое изменение синтаксиса, приведенный ниже текст намного понятнее, и в большинстве IDE вы можете ввести /** и нажать enter, чтобы автоматически сгенерировать его. По сравнению с приведенным выше примером этот комментарий имеет больше смысла и назначения на странице.

/**
 * Эта функция использует идентификатор пользователя и корзину покупок
 * перебирает товары, чтобы отправить счет через api
 * возвращает json 
 */

А теперь немного волшебства, давайте поднимем этот комментарий на следующий уровень:

Уверен, вы этого не ожидали! Я понятия не имею, почему в учебниках не уделяется особого внимания такому форматированию комментариев, это сильно меняет правила игры, не говоря уже об экономии времени. Итак, что же происходит выше?

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

Как часто делать комментарии?

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

Заключение

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