JavaScript с нуля

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

Есть несколько вариантов комментариев в коде. Один из них — это однострочные комментарии, которые обозначаются двумя наклонными чертами // и содержат сообщение. Такой вид комментариев мы уже видели.

Мы можем размещать их в отдельно выделенной строке:

// Возвращает больший из двух аргументов.

function max(a, b) {

if (a > b) {

return a;

} 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/.