JavaScript с нуля - [14]

КОРОТКО О ГЛАВНОМ

Итак, вы познакомились с циклами for и способами их использования и параллельно затронули их аналоги while и do…while. Пока что мы не будем часто использовать циклы. По мере погружения в более сложные ситуации вроде сбора данных, элементов DOM, управления текстом и другие процессы мы будем прибегать к их использованию все чаще. Главное — не забывать изученную в этой главе информацию.

Если у вас есть вопросы по пройденному материалу, не стесняйтесь задавать их на форуме https://forum.kirupa.com и вы получите оперативный ответ если не от меня, то от других умнейших и готовых помочь разработчиков.

1 Мегатрон «Meг» Гриффин — персонаж мультсериала «Гриффины», закомплексованная и неуверенная в себе девушка, над которой подшучивают семья и окружающие. — Примеч. ред.

6. Комментирование кода… что за?!

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

let xPos = -500;

function boringComputerStuff() {

xPos += 5;

if (xPos > 1000) {

xPos = -500;

}

}

boringComputerStuff();

Но скоро мы убедимся, что это совсем не так. У кода есть и другая аудитория — люди.

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

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

Поехали!

Что такое комментарии?

Комментарии — это то, что мы пишем в виде части кода для передачи информации читающим его:

// Это вам за то, что не пригласили меня на день рождения!

let blah = true;

function sweetRevenge() { while (blah) {

// Бесконечные диалоговые окна! Ха-ха-ха!!!!

alert("Hahahaha!");

}

}

sweetRevenge();

В этом примере комментарии отмечены символами // и дают относительно точную информацию о коде, который описывают.

О комментариях важно помнить, что они не выполняются вместе с остальным кодом. JavaScript игнорирует комментарии. Вы ему не нравитесь, и его не волнует, что вы хотите сказать, поэтому даже не парьтесь по поводу синтаксиса, пунктуации и всего того, что важно при написании кода. Комментарии нужны только для понимания действий с отдельными фрагментами кода.

Помимо этого, комментарии служат еще одной цели. Их можно оставлять, чтобы отмечать строки кода, выполнять которые сейчас не нужно:

function insecureLogin(input) {

if (input == "password") {

// let key = Math.random() * 100000;

// processLogin(key);

}

return false;

}

В этом примере две нижеприведенные строки отображаются в редакторе, но не выполняются:

// let key = Math.random() * 100000;

// processLogin(key);

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

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

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

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

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

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