Как мы знаем из главы Структура кода, комментарии могут быть однострочными: начинающимися с // и многострочными: /* ... */ .
Обычно мы используем их, чтобы описать, как и почему работает код.
На первый взгляд комментарии могут показаться очевидными, но новички в программировании часто используют их неправильно.
Новички склонны использовать комментарии, чтобы объяснить, «что происходит в коде». Так:
// Этот код сделает то (...) и то (...) // ...и кто знает что еще... очень; сложный; код;
Но в хорошем коде количество таких «пояснительных» комментариев должно быть минимальным. Серьезно, код должен быть легко понятен и без них.
На этот счет есть отличное правило: «если код настолько неясен, что требует комментариев, то, возможно, его следует переписать».
Иногда полезно заменить фрагмент кода функцией, как здесь:
функция showPrimes(n) {
следующийПрайм:
for (пусть я = 2; я < n; я++) {
// проверяем, является ли i простым числом
for (пусть j = 2; j < i; j++) {
если (i % j == 0) продолжить nextPrime;
}
предупреждение (я);
}
} Лучший вариант с вынесенной функцией isPrime :
функция showPrimes(n) {
for (пусть я = 2; я < n; я++) {
if (!isPrime(i)) продолжить;
предупреждение (я);
}
}
функция isPrime(n) {
for (пусть я = 2; я < n; я++) {
если (n % i == 0) вернуть ложь;
}
вернуть истину;
}Теперь мы можем легко понять код. Сама функция становится комментарием. Такой код называется самоописательным .
А если у нас есть длинный «кодовый лист» вроде этого:
// сюда добавляем виски
for(пусть я = 0; я <10; я++) {
пусть падение = getWhiskey();
запах (капля);
add(капля, стакан);
}
// сюда добавляем сок
for(let t = 0; t < 3; t++) {
пусть помидор = getTomato();
рассмотреть(помидор);
дать соку = нажать(помидор);
добавить(сок, стакан);
}
// ...Тогда, возможно, было бы лучшим вариантом реорганизовать его в такие функции, как:
addWhiskey(стакан);
addJuice(стакан);
функция addWhiskey(контейнер) {
for(пусть я = 0; я <10; я++) {
пусть падение = getWhiskey();
//...
}
}
функция addJuice(контейнер) {
for(let t = 0; t < 3; t++) {
пусть помидор = getTomato();
//...
}
}Опять же, сами функции говорят, что происходит. Комментировать нечего. А также структура кода становится лучше при разделении. Понятно, что делает каждая функция, что она принимает и что возвращает.
На самом деле полностью избежать «разъяснительных» комментариев невозможно. Есть сложные алгоритмы. И есть умные «твики» для оптимизации. Но в целом мы должны стараться сделать код простым и понятным.
Так что пояснительные комментарии обычно плохи. Какие комментарии хорошие?
Опишите архитектуру
Предоставьте общий обзор компонентов, того, как они взаимодействуют, каков поток управления в различных ситуациях… Короче говоря — взгляд на код с высоты птичьего полета. Существует специальный язык UML для построения архитектурных диаграмм высокого уровня, объясняющих код. Определенно стоит изучить.
Параметры и использование функций документа
Существует специальный синтаксис JSDoc для документирования функции: использование, параметры, возвращаемое значение.
Например:
/**
* Возвращает x, возведенный в n-ю степень.
*
* @param {number} x Число, которое нужно повысить.
* @param {number} n Степень должна быть натуральным числом.
* @return {число} x возведено в n-ю степень.
*/
функция pow(x, n) {
...
}Такие комментарии позволяют нам понять назначение функции и правильно ее использовать, не заглядывая в ее код.
Кстати, многие редакторы, такие как WebStorm, также могут их понимать и использовать для автозаполнения и некоторой автоматической проверки кода.
Также существуют такие инструменты, как JSDoc 3, которые могут генерировать HTML-документацию из комментариев. Дополнительную информацию о JSDoc можно прочитать на странице https://jsdoc.app.
Почему задача решена именно так?
Важно то, что написано. Но то, что не написано, может быть еще важнее для понимания того, что происходит. Почему задача решается именно так? Код не дает ответа.
Если существует множество способов решения задачи, то почему именно этот? Особенно, если это не самое очевидное.
Без таких комментариев возможна следующая ситуация:
Вы (или ваш коллега) открываете код, написанный некоторое время назад, и видите, что он «неоптимален».
Вы думаете: «Какой же я тогда был глупый, и насколько я умнее сейчас», и переписываете, используя «более очевидный и правильный» вариант.
…Желание переписать было хорошим. Но в процессе вы увидите, что «более очевидного» решения на самом деле не хватает. Ты даже смутно помнишь почему, ведь ты уже давно это попробовал. Вы возвращаетесь к правильному варианту, но время потрачено зря.
Комментарии, объясняющие решение, очень важны. Они помогают продолжить развитие в правильном направлении.
Какие-нибудь тонкие особенности кода? Где они используются?
Если в коде есть что-то тонкое и нелогичное, это определенно стоит прокомментировать.
Важным признаком хорошего разработчика являются комментарии: их наличие и даже их отсутствие.
Хорошие комментарии позволяют нам хорошо поддерживать код, возвращаться к нему после задержки и использовать его более эффективно.
Прокомментируйте это:
Общая архитектура, вид на высоком уровне.
Использование функции.
Важные решения, особенно если они не очевидны сразу.
Избегайте комментариев:
Это говорит о том, «как работает код» и «что он делает».
Добавляйте их только в том случае, если невозможно сделать код настолько простым и понятным, что они не потребуются.
Комментарии также используются для инструментов автодокументирования, таких как JSDoc3: они читают их и генерируют HTML-документы (или документы в другом формате).