Рубрики
Без рубрики

Комментирующий код в JavaScript – типы и лучшие практики

В этом руководстве мы перейдем, как комментировать код в JavaScript. Мы пройдемся по типы комментариев, включая DocStrings, а также несколько лучших практик для написания комментариев в JavaScript.

Автор оригинала: Abhilash Kakumanu.

Вступление

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

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

Комментарии Примечаются ли заметки, написанные в коде, которые игнорируются двигателем 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 Docstrings

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

Многострочные комментарии начинаются с /* и заканчиваться */ :

/* 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
*/

Здесь многострочный комментарий используется для описания Tic-Tac-Toe. Как правило, многострочные комментарии используются для введения и объяснения раздела кода, где одно строка/предложение недостаточно.

Другой тип многострочных комментариев может быть виден так же:

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

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

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

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

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

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

Рассмотрим следующий код:

console.log("Working code");
console.log("Erroneous code);

Если бы мы хотели удалить второе утверждение, но не хотите удалять его навсегда, мы можем просто комментировать это:

console.log("Working code");
//console.log("Erroneous code);

Pro Tip : В большинстве редакторов кода мы можем использовать ярлык клавиатуры 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 Docstrings.

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