Кажется, что все, что мы пишем в редакторе кода, предназначено исключительно для браузера:
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-страниц. Это позволяет тратить больше времени на написание самого кода и в то же время помогает пользователям разобраться в действиях вашего кода и понять, как использовать его отдельные части.
Если вы хотите подробнее узнать об использовании 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;
/*
Для возвращения в прежнее состояние нужно убедиться, что
мы выбираем его в нашем UI. Это означает, что производится
итерация по каждому состоянию выпадающего списка, пока
не будет найдено совпадение. Когда совпадение найдено,
нужно убедиться, чтобы оно было выбрано.
*/
for (let i = 0; i < selectContent.length; i++) {
let stateInSelect = selectContent.options[i].innerText;
if (stateInSelect == state) {
stateIndex = i;
}
}
selectContent.selectedIndex = stateIndex;
}
Обратите внимание, что наш комментарий грамотно выделен пробелами и его отлично видно в остальной части кода. Если ваши комментарии будут разбросаны где попало и их будет сложно опознать, это сильно замедлит чтение кода как для вас, так и для других.
Не комментируйте очевидные вещи. Если строка кода говорит сама за себя, не стоит тратить время на объяснение ее действий. Это допустимо, только если в ней кроется некое едва уловимое поведение, которое вы хотите обозначить в качестве предупреждения. В остальных же случаях лучше потратить время на комментирование менее понятных участков кода.
Эти рекомендации помогут вам комментировать код значительно эффективнее. Если вы работаете в крупном проекте с другими людьми, могу вас заверить, что в вашей команде уже существует устоявшийся регламент, определяющий правильное написание комментариев. Уделите время ознакомлению с этим регламентом и следуйте ему. В итоге останутся довольными все: как вы, так и ваша команда.
КОРОТКО О ГЛАВНОМ
Комментарии зачастую рассматриваются как вынужденное зло. В конце концов, стали бы вы тратить несколько минут на то, чтобы прокомментировать то, что вы и так прекрасно понимаете, или предпочли бы поработать над очередной «вкусной» частью функциональности? Я предпочитаю относиться к комментариям как к «долгосрочному вложению». Значение и польза комментариев зачастую проявляются не сразу, а становятся очевидными, когда с вашим кодом начинают работать другие люди, а также если вам приходится вновь вернуться к своему коду, а вы уже забыли, что он делает и как работает. Не жертвуйте долгосрочной экономией времени в перспективе ради незначительного ускорения в работе сейчас. Делайте ставки на однострочные (//) и многострочные (/* и */) комментарии уже сегодня, пока еще не слишком поздно.
И если у вас появились какие-либо вопросы по этой теме, обращайтесь за оперативной помощью ко мне и другим разработчикам на форуме https://forum.kirupa.com.