Комментарии в JavaScript

Введение

В этой главе рассматривается всё необходимое для написания хороших комментариев в JavaScript: два синтаксиса комментариев (// — строчные и /* */ — блочные), JSDoc-комментарии для документирования функций, разница между полезными и вредными комментариями, а также способы временного отключения кода при отладке. Комментарии — это текст, который движок JavaScript полностью игнорирует при выполнении программы: они существуют исключительно для людей. Комментарии объясняют код всем, кто будет читать его позже, — включая вас самих и ваших коллег. Поскольку они не участвуют в выполнении, комментарии не влияют на производительность во время работы программы. (Одна связанная директива, которую движок всё же читает, — это "use strict"; несмотря на то что она выглядит как строка в начале файла, она меняет поведение кода — см. главу о строгом режиме.)

Зачем комментировать код в JavaScript

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

• Документировании кода: объясняет сложную логику или причину тех или иных решений.
• Читаемости кода: улучшает понимание потока выполнения и функциональности программы.
• Отладке: позволяет быстро включать или отключать части кода при тестировании.
• Командной работе: помогает другим разработчикам понять ход ваших мыслей.

Типы комментариев в JavaScript

JavaScript поддерживает два основных вида комментариев:

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

Однострочные комментарии начинаются с // и распространяются до конца текущей строки. Всё, что стоит после // на этой строке, игнорируется. Они могут занимать отдельную строку или располагаться в конце строки с кодом (встроенный комментарий):

// This whole line is a comment
let a = 5, b = 10;

let sum = a + b; // inline comment: add the two values

Поскольку комментарий // действует только до конца строки, следующая строка снова является обычным кодом — «закрывать» его не нужно.

Многострочные комментарии

Многострочные комментарии (также называемые блочными) начинаются с /* и заканчиваются */. Всё между ними игнорируется, даже если текст занимает много строк. Используйте их для развёрнутых пояснений:

/*
  Returns the sum of two numbers.
  Both arguments are expected to be numbers;
  passing strings will concatenate instead of add.
*/
function add(a, b) {
    return a + b;
}

Блочный синтаксис можно также использовать внутри строки, например для обозначения аргумента: setTimeout(run, 1000 /* ms */).

Важно — блочные комментарии не вкладываются друг в друга. Символы */ завершают комментарий при первом их появлении, поэтому обернуть код, уже содержащий /* ... */, в ещё один блочный комментарий не получится. Внутренний */ закроет комментарий раньше времени, и оставшийся текст станет рабочим кодом:

/*
  /* inner */
  alert('this still runs!');
*/

Копировать

Чтобы закомментировать область с блочными комментариями, используйте // перед каждой строкой.

Хорошие и плохие комментарии: объясняйте «почему», а не «что»

Самое важное правило: комментируйте почему, а не что. Код уже сам говорит о том, что делает; хороший комментарий раскрывает намерение, компромисс или неочевидное ограничение, которое код не может выразить самостоятельно.

// Bad: just restates the code — adds noise, can go stale
let total = 0; // set total to 0

// Good: explains a non-obvious constraint
const RETRY_LIMIT = 3; // the payment API rejects bursts above 3 calls/sec

По возможности отдавайте предпочтение самодокументирующемуся коду, а не комментариям. Хорошо названная переменная или небольшая функция часто полностью снимают необходимость в комментарии:

// Needs a comment because the intent is hidden:
if (u.a && Date.now() - u.l < 86400000) { /* active in last 24h */ }

// No comment needed — the names say it:
const isActive = user.isVerified && wasSeenInLast24Hours(user);
if (isActive) {
  // ...
}

Ещё несколько рекомендаций:

1. Поддерживайте актуальность. Комментарий, противоречащий коду, хуже, чем его отсутствие — читатель не знает, чему доверять.
2. Будьте лаконичны. Объясняйте причины, а не каждый шаг.
3. Не оставляйте закомментированный неиспользуемый код навсегда. Удаляйте его: система контроля версий всё помнит.

Отключение кода через комментарии

При отладке часто нужно отключить строку или блок кода, не удаляя их. Добавьте // перед строкой или оберните область в /* */:

let value = compute();
// console.log('Debug:', value); // temporarily silenced

/*
expensiveLogging(value);
sendToAnalytics(value);
*/

Это удобно для выявления проблемного участка кода. Многие редакторы переключают этот режим с помощью сочетания клавиш. О более чистых альтернативах отладке через console.log см. главу Console API.

Маркеры TODO и FIXME

Распространённая практика — помечать незавершённую работу меткой TODO (нужно сделать позже) или FIXME (известная ошибка). Редакторы и линтеры могут собирать эти метки в список:

// TODO: optimize this loop for large data sets
// FIXME: breaks when input is an empty array

JSDoc: документирование функций

JSDoc — стандарт документирования функций с помощью специального блочного комментария, начинающегося с /** (две звёздочки). Теги @param и @returns описывают входные параметры и возвращаемое значение. Инструменты и редакторы читают эти комментарии, чтобы показывать подсказки и генерировать HTML-документацию.

/**
 * Adds two numbers together.
 * @param {number} a - The first addend.
 * @param {number} b - The second addend.
 * @returns {number} The sum of a and b.
 */
function add(a, b) {
    return a + b;
}

console.log(add(2, 3)); // 5

JSDoc особенно хорошо сочетается с функциями: документирование параметров и возвращаемых типов делает контракт функции понятным без необходимости читать её тело. Другие распространённые теги: @throws, @example и @deprecated.

Заключение

Использование эффективных комментариев в JavaScript — это не просто навык программирования, но и коммуникационное умение. Оно существенно влияет на поддерживаемость и масштабируемость кода. Освоив комментарии в JavaScript, вы не только улучшите свой код, но и повысите эффективность совместной работы с другими участниками команды.

Помните: хорошо прокомментированный код — это отражение вдумчивого и профессионального разработчика. Используйте возможности комментирования, и ваш JavaScript-код станет более доступным и простым в сопровождении.

Практика