} else {
return b;
}
}
Или в одну строку с инструкцией:
let zorb = "Alien"; // Раздражать жителей планеты.
Только вам решать, где именно размещать комментарий. Выбирайте место, которое покажется наиболее подходящим.
Поскольку мне нравится быть заезженной пластинкой, еще раз повторю: комментарии не выполняются вместе с остальной частью приложения. Они видны только вам, мне и, возможно, нашим друзьям. Если последняя фраза вам непонятна, значит, вы, скорее всего, не смотрели одну из величайших комедий нашего века (к/ф «Он, я и его друзья»). В таком случае я настоятельно рекомендую отвлечься от учебы и потратить пару часов на исправление этого упущения.
Комментарии с помощью JSDoc
Когда мы пишем код и знаем, что с ним будут работать другие, наверняка захочется передать информацию наиболее простым способом и избавить от необходимости пересматривать весь исходник. Такой способ есть, и все благодаря инструменту JSDoc, который предполагает несколько иной подход к написанию комментариев:
/**
* Перетасовывает содержимое массива (Array).
* @this {Array}
* @returns {Array} Текущий массив с перетасованным содержимым.
*/
Array.prototype.shuffle = function () {
let input = this;
for (let i = input.length — 1; i >= 0; i-) {
let randomIndex = Math.floor(Math.random() * (i + 1));
let itemAtIndex = input[randomIndex];
input[randomIndex] = input[i];
input[i] = itemAtIndex;
}
return input;
}
Как только вы оставили комментарии к файлу, воспользуйтесь JSDoc для экспорта согласующихся частей комментариев в удобно просматриваемый набор HTML-страниц. Это позволяет тратить больше времени на написание самого кода и в то же время помогает пользователям разобраться в действиях вашего кода и понять, как использовать его отдельные части.
Если вы хотите подробнее узнать об использовании JSDoc, посетите сайт этого проекта https://jsdoc.app/.
Многострочные комментарии
Сложность с однострочными комментариями состоит в том, что приходится указывать символы // в начале каждой строки, к которой нужно его оставить. Это может быть очень утомительным, особенно если вы пишите большой комментарий или комментируете большой кусок кода.
Для таких случаев существует другой способ оформления комментариев, а именно с помощью символов /* и */, которые определяют начало и конец. И в результате получаются многострочные комментарии:
/*
let mouseX = 0; let mouseY = 0;
canvas.addEventListener("mousemove", setMousePosition, false);
function setMousePosition(e) {
mouseX = e.clientX;
mouseY = e.clientY;
}
*/
Вместо добавления символов // в каждую строку можно использовать символы /* и */, что сэкономит наши время и нервы.
Мы будем комбинировать однострочные и многострочные комментарии в зависимости от того, что хотим задокументировать. Поэтому нам нужно знать, как использовать оба описанных подхода.
Лучшие способы комментирования
Теперь, когда мы уже имеем достаточное представление о том, что такое комментарии, и знаем несколько способов их написания в JavaScript, давайте поговорим о том, как их правильно использовать, чтобы облегчить чтение кода.
Всегда комментируйте код по ходу его написания. Создание комментариев — ужасно скучное занятие, но оно является важной частью написания кода. Вам и другим будет гораздо проще и быстрее понять код, прочитав комментарий, чем просматривать строка за строкой скучную писанину на JavaScript.
Не откладывайте написание комментариев на потом. Такой подход ведет к прокрастинации, которая будет возрастать при выполнении рутинной работы. Если вы не прокомментируете код по ходу написания, то, скорее всего, этого уже не сделаете, что точно никому не пойдет на пользу.
Используйте обычные слова и поменьше JavaScript. Комментарии — это одно из немногих мест, где при написании программы вы можете свободно пользоваться человеческим языком. Не усложняйте комментарии кодом без необходимости. Выражайтесь ясно, сжато, словами.
Используйте пустые пространства. Вам нужно добиться того, чтобы при просматривании больших блоков кода комментарии выделялись и легко прослеживались. Для этого нужно активнее пользоваться пробелом и клавишами Enter-Return. Взгляните на следующий пример:
function selectInitialState(state) {
let selectContent = document.querySelector("#stateList"); let
stateIndex = null;
/*
Для возвращения в прежнее состояние нужно убедиться, что