Комментирование кода в JavaScript - типы и передовые методы
Основная цель написания кода - чтобы компьютер мог интерпретировать его как команды. Однако также важно, чтобы код, который мы пишем, также легко интерпретировался другими разработчиками.
Вы когда-нибудь возвращались к проекту и испытывали трудности с пониманием внутренней логики? Вероятно, это потому, что указанный проект не был прокомментирован должным образом.
Комментарии - это заметки, написанные в коде, которые игнорируются движком JavaScript, что означает, что они никоим образом не влияют на вывод. Их единственная цель - описать, как и почему код работает, другим разработчикам и вам самим.
В этой статье мы рассмотрим, как комментировать код JavaScript, какие типы комментариев существуют, а также некоторые передовые практики.
Однострочные комментарии
Однострочные комментарии обычно используются для комментирования части или всей строки кода. Однострочные комментарии в JavaScript начинаются с //. Интерпретатор будет игнорировать все, что находится справа от этой управляющей последовательности, до конца строки.
Давайте посмотрим на пример однострочного комментария в действии:
// Print "Hello World" in the console
console.log("Hello World");
Здесь мы используем однострочный комментарий, чтобы описать, что делает следующая строка кода.
Если однострочный комментарий появляется в конце строки кода, он называется встроенным комментарием.
Обычно они используются для добавления быстрых аннотаций:
let c = a + b; // Assign sum of a, b to c
Многострочные комментарии и строки документации JavaScript
Если мы хотим добавить примечание, которое занимает несколько строк, мы можем выбрать многострочные комментарии или комментарии на уровне блока.
Многострочные комментарии начинаются /* и заканчиваются */:
/* The following program contains source code for a game called Tic-tac-toe.
It is a paper-and-pencil game for two players, X and O, who take turns marking the spaces in a 3×3 grid.
The player who succeeds in placing three of their marks in a horizontal, vertical, or diagonal row is the winner
*/
Здесь многострочный комментарий используется для описания крестиков-ноликов. Как правило, многострочные комментарии используются для введения и объяснения раздела кода, где одной строки / предложения недостаточно.
Часто можно увидеть и другой тип многострочного комментария:
/**
* The following program contains source code for a game called Tic-tac-toe.
* It is a paper-and-pencil game for two players, X and O, who take turns marking the
* spaces in a 3×3 grid.
* The player who succeeds in placing three of their marks in a horizontal, vertical, or
* diagonal row is the winner
*/
Часто эти комментарии могут включать информацию о выполняемом коде, такую как параметры функции или даже автора кода:
/**
* Function that greets a user
* @author John
* @param {String} name Name of the user
* @return {String} Greeting message
*/
function greetUser(name) {
return `Greetings, ${name}!`;
}
Эти комментарии называются DocStrings, поскольку они по сути являются строками (комментариями), составляющими документацию вашего кода.
Эти типы комментариев действительно полезны для других разработчиков в вашей команде, так как вы можете уточнить, каковы ожидаемые входные данные, каковы выходные данные, а также к кому обращаться в случае необходимости.
Дополнительным преимуществом является то, что вы можете создавать документацию на основе этих строк документа.
Использование комментариев для отладки
Помимо заметок, комментарии также можно использовать для быстрого предотвращения выполнения кода в целях отладки. Это возможно, потому что движки JavaScript не интерпретируют закомментированный код.
Если есть ошибочная строка, которая вызывает проблемы, мы можем просто "закомментировать ее", чтобы отключить ее, не удаляя строку. Это может быть связано с реальными отладчиками, чтобы помочь вам оценить, что происходит.
Рассмотрим следующий код:
console.log("Working code");
console.log("Erroneous code);
Если мы хотим удалить второй оператор, но не хотим удалять его навсегда, мы можем просто закомментировать его:
console.log("Working code");
//console.log("Erroneous code);
Совет: в большинстве редакторов кода мы можем использовать сочетание клавиш Ctrl + / для Windows и Cmd + / для Mac, чтобы закомментировать одну строку кода.
Кроме того, вы также можете закомментировать целые разделы, если не уверены, удалять ли их или нет:
/*console.log("Entering for loop");
for (let i = 0; i < 100; i++) {
console.log(i);
}*/
Хорошие практики комментирования
Во-первых, комментирование - это не повод для написания нечитаемого кода, а затем просто исправить его пятью абзацами комментариев, объясняющих его. Сначала мы должны сосредоточиться на написании чистого, не требующего пояснений кода, который позже можно улучшить с помощью конструктивных комментариев.
Используйте комментарии, чтобы объяснить, почему вы что-то сделали, а не как вы это сделали. Если вы обнаружите, что объясняете, как вы что-то сделали, то пора сделать шаг назад и реорганизовать ваш код в нечто самоочевидное.
Еще один совет - не писать очевидные и излишние комментарии. Например, совершенно не нужен следующий комментарий:
// Prints out the result
console.log(result)
Существуют полезные инструменты, такие как JSDOC 3, которые могут создавать документацию только на основе комментариев в вашем коде, которые отформатированы как DocStrings, описанные выше.
Вывод
В этой статье мы рассмотрели, что такое комментарии и как их создавать в JavaScript. Мы рассмотрели различные типы комментариев - однострочные и многострочные комментарии, а также строки документации JavaScript.
Мы также увидели, как отлаживать наш код, используя технику, называемую «комментирование», и, наконец, подытожили некоторые хорошие практики комментирования.
