Вступление

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

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

Комментарии - это заметки, написанные в коде, которые игнорируются движком 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 , поскольку они по сути являются строками (комментариями), составляющими документацию вашего кода.

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

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

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

Помимо заметок, комментарии также можно использовать для быстрого предотвращения выполнения кода в целях отладки. Это возможно, потому что движки 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.

Мы также увидели, как отлаживать наш код, используя технику, называемую «комментирование», и, наконец, подытожили некоторые хорошие практики комментирования.