JavaScript с нуля

Лучшие способы комментирования

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