Два вида комментариев
В JavaScript есть два синтаксиса комментариев. Однострочный комментарий начинается с // и тянется до конца строки:
Блочный комментарий в JavaScript открывается через /* и закрывается ближайшим */. Внутри можно уместить сколько угодно строк:
Обе формы полностью игнорируются движком JavaScript. Они существуют для людей — для тебя, твоих коллег и тебя-через-полгода, когда ты снова откроешь этот код.
Однострочный комментарий в JS
// — это то, чем ты будешь пользоваться чаще всего. Всё, что идёт после // в той же строке, считается комментарием; следующая строка — это снова код:
Комментарии в конце строки (после инструкции) вполне уместны для коротких пометок. Но если пометка разрослась и переносится на следующую строку — лучше вынести её отдельной строкой над кодом. Длинные хвостовые комментарии редакторы обрезают, а читатели просто игнорируют.
Блочный комментарий в JavaScript
Синтаксис /* */ стоит доставать из кармана в двух случаях: когда комментарий не умещается в одну строку и когда его нужно воткнуть прямо посреди выражения.
Есть один подвох: блочные комментарии не вкладываются друг в друга. Первый же */ закрывает комментарий, даже если вам казалось, что вы всё ещё внутри внешнего:
/* внешний /* внутренний */ всё ещё внешний */
// SyntaxError — первый */ закрыл блок,
// и "всё ещё внешний */" теперь некорректный код.
Если нужно закомментировать код, в котором уже есть /* */, используйте // на каждой строке.
Как временно отключить код
Во время отладки часто приходится на время выключать пару строк. Для этого подойдёт любой из видов комментариев:
В любом редакторе для этого есть горячие клавиши — Ctrl+/ на Windows/Linux и Cmd+/ на Mac — они переключают // для выделенных строк. Выучите один раз и будете пользоваться каждый день.
Закомментированный код — это временная мера. Не тащите в коммиты кладбища мёртвого кода с подписями вроде // старая версия, пусть полежит на всякий случай. Git и так помнит всю историю. Удаляйте смело.
Комментируйте «почему», а не «что»
Это то самое правило, которое отделяет полезные комментарии от информационного шума. Код и так показывает, что он делает. Хороший комментарий объясняет, зачем.
Шум:
Такие комментарии не сообщают читателю ничего, чего нельзя было бы понять из самого кода. Сравните:
Оба комментария поясняют то, чего из самого кода не понять — внешнее ограничение, задокументированную особенность. Вот это и есть планка. Если без комментария никто не запутается — значит, он не тянул свой вес.
JSDoc: комментарии, которые читают инструменты
JSDoc — это соглашение о том, как писать блочные комментарии, структурированно описывающие функции. Редакторы и проверяльщики типов умеют их читать и за счёт этого выдают более толковые подсказки автодополнения и всплывающую документацию:
Открытие /** (с двумя звёздочками) — это как раз то, что превращает обычный блочный комментарий в JSDoc. Не стоит писать JSDoc к каждой функции — он действительно полезен для публичных API, общих утилит и тех мест, где типы не очевидны из самого кода.
Несколько полезных привычек
- Пишите комментарий рядом с кодом, к которому он относится. Комментарий, который висит за десять строк до нужного места, со временем перестаёт соответствовать коду.
- Меняете код — обновляйте комментарий. Устаревший комментарий хуже, чем его отсутствие: он напрямую вводит в заблуждение следующего читателя.
- Хорошее имя лучше длинного комментария. К
const d = 86400000;комментарий нужен. Кconst MILLISECONDS_PER_DAY = 86_400_000;— уже нет. - Помечайте временные проблемы через
TODO:илиFIXME:. Большинство редакторов подсвечивают такие метки, и их легко потом найти поиском.
Важно: не путайте комментарии HTML и JavaScript
Если вы пишете JavaScript прямо в HTML-файле, следите за тем, какой синтаксис комментариев используете. В HTML это <!-- -->, а в JavaScript — // и /* */. Внутри тега <script> работают только «джаваскриптовые» варианты:
<script>
// Правильно — JS-комментарий внутри <script>
/* Тоже правильно */
<!-- Неправильно — это HTML-комментарий, он сломает ваш JS -->
console.log("hi");
</script>
Браузеры исторически терпели конструкцию <!-- --> внутри скриптов — это наследие совсем древних времён, так что считайте её сломанной и просто идите дальше.
Дальше: объявление переменных
Раз уж вы научились оставлять комментарии в коде, пора этот код и писать. В JavaScript переменную можно объявить тремя способами — let, const и var — и выбор между ними будет первым осмысленным решением, которое вы принимаете буквально в каждой строке. Об этом — в следующей главе.
Часто задаваемые вопросы
Как написать комментарий в JavaScript?
Для однострочного комментария используйте // — всё, что идёт после него до конца строки, игнорируется интерпретатором. Для блочного — /* ... */, он может занимать сколько угодно строк. Оба варианта работают и в .js-файлах, и внутри тега <script> в HTML.
Чем отличаются // и /* */ в JavaScript?
// действует только до конца текущей строки. /* */ начинается с /* и заканчивается на ближайшем */, поэтому его можно растянуть на несколько строк или вставить прямо в середину выражения. Короткая пометка — //, многострочное пояснение или комментарий внутри выражения — /* */.
Как закомментировать блок кода в JavaScript?
Оберните его в /* */ или добавьте // в начало каждой строки. В большинстве редакторов для этого есть хоткей — Ctrl+/ (Cmd+/ на Mac) переключает // на выделенных строках. Только не вкладывайте /* */ внутрь другого /* */ — первый же */ закроет внешний комментарий, и вы получите синтаксическую ошибку.
Когда вообще стоит писать комментарии?
Объясняйте почему, а не что. Если в коде есть что-то неочевидное — костыль, бизнес-правило, оптимизация — напишите, зачем так сделано. Не нужно пересказывать то, что и так видно в коде. Хорошие имена переменных и функций избавляют от большинства комментариев.
