Как делать комментарии в javascript

JavaScript Урок 5 Комментарии

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

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

Комментарии добавляются для пояснения кода JavaScript, или чтобы сделать код более читабельным.

Однострочные комментарии начинаются с //.

Следующий пример использует однострочные комментарии, чтобы пояснить код:

Пример

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

Многострочные комментарии начинаются с /* и заканчиваются */.

Следующий пример использует многострочный комментарий для пояснения кода:

Пример

Использование Комментариев для Предотвращения Исполнения

В следующем примере комментарий используется для предотвращения исполнения одной строки кода (это может быть полезно при отладке):

Пример

В следующем примере комментарий используется для предотвращения выполнения блока кода (это может быть полезно при отладке):

Пример

Использование Комментариев в Конце Строки

В следующем примере комментарий помещается в конце строки кода:

Комментарии

Как мы знаем из главы Структура кода, комментарии могут быть однострочными, начинающимися с // , и многострочными: /* . */ .

Обычно мы их используем, чтобы описать, как и почему работает код.

На первый взгляд, в комментариях нет ничего сложного, но новички в программировании часто применяют их неправильно.

Плохие комментарии

Новички склонны использовать комментарии, чтобы объяснять, «что делает код». Например, так:

// Этот код делает это (. ) и вот это (. ) // . и кто знает, что ещё. очень; сложный; код;

Но в хорошем коде количество «объясняющих» комментариев должно быть минимальным. Серьёзно, код должен быть таким, чтобы его можно было понять без комментариев.

Про это есть хорошее правило: «Если код настолько запутанный, что требует комментариев, то, может быть, его стоит переделать?»

Рецепт: выносите код в функции

Иногда выгодно заменить часть кода функцией, например, в таком случае:

function showPrimes(n) < nextPrime: for (let i = 2; i < n; i++) < // проверяем, является ли i простым числом for (let j = 2; j < i; j++) < if (i % j == 0) continue nextPrime; >alert(i); > >

Лучший вариант – использовать отдельную функцию isPrime :

function showPrimes(n) < for (let i = 2; i < n; i++) < if (!isPrime(i)) continue; alert(i); >> function isPrime(n) < for (let i = 2; i < n; i++) < if (n % i == 0) return false; >return true; >

Теперь код легче понять. Функция сама становится комментарием. Такой код называется самодокументированным.

Рецепт: создавайте функции

И если мы имеем такой длинный кусок кода:

// здесь мы добавляем виски for(let i = 0; i < 10; i++) < let drop = getWhiskey(); smell(drop); add(drop, glass); >// здесь мы добавляем сок for(let t = 0; t < 3; t++) < let tomato = getTomato(); examine(tomato); let juice = press(tomato); add(juice, glass); >// . 

То будет лучше отрефакторить его с использованием функций:

addWhiskey(glass); addJuice(glass); function addWhiskey(container) < for(let i = 0; i < 10; i++) < let drop = getWhiskey(); //. >> function addJuice(container) < for(let t = 0; t < 3; t++) < let tomato = getTomato(); //. >>

Здесь комментарии тоже не нужны: функции сами говорят, что делают (если вы понимаете английский язык). И ещё, структура кода лучше, когда он разделён на части. Понятно, что делает каждая функция, что она принимает и что возвращает.

В реальности мы не можем полностью избежать «объясняющих» комментариев. Существуют сложные алгоритмы. И есть хитрые уловки для оптимизации. Но в целом мы должны стараться писать простой и самодокументированный код.

Хорошие комментарии

Итак, обычно «объясняющие» комментарии – это плохо. Но тогда какой комментарий считается хорошим?

Описывайте архитектуру Сделайте высокоуровневый обзор компонентов, того, как они взаимодействуют, каков поток управления в различных ситуациях… Если вкратце – обзор кода с высоты птичьего полёта. Существует специальный язык UML для создания диаграмм, разъясняющих архитектуру кода. Его определённо стоит изучить. Документируйте параметры и использование функций Есть специальный синтаксис JSDoc для документирования функций: использование, параметры, возвращаемое значение.

/** * Возвращает x, возведённое в n-ную степень. * * @param x Возводимое в степень число. * @param n Степень, должна быть натуральным числом. * @return x, возведённое в n-ную степень. */ function pow(x, n)

Подобные комментарии позволяют нам понимать назначение функции и правильно её использовать без необходимости заглядывать в код.

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

Также существуют инструменты, например, JSDoc 3, которые умеют генерировать HTML-документацию из комментариев. Получить больше информации о JSDoc вы можете здесь: https://jsdoc.app.

Почему задача решена именно таким способом?

Важно то, что написано. Но то, что не написано, может быть даже более важным, чтобы понимать происходящее. Почему задача решена именно этим способом? Код не даёт ответа.

Если есть несколько способов решить задачу, то почему вы выбрали именно этот? Особенно если ваш способ – не самый очевидный.

Без подобных комментариев возможна следующая ситуация:

1. Вы (или ваш коллега) открываете написанный некоторое время назад код и видите, что в нём есть, что улучшить.
2. Вы думаете: «Каким глупым я раньше был и насколько умнее стал сейчас», и переписываете его на «более правильный и оптимальный» вариант.
3. …Желание переписать код – это хорошо. Но в процессе вы понимаете, что «оптимальное» решение на самом деле не такое уж и оптимальное. Вы даже смутно припоминаете, почему, так как в прошлый раз вы уже его пробовали. Вы возвращаетесь к правильному варианту, потратив время зря.

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

В коде есть какие-то тонкости? Где они используются?

Если в коде есть какие-то тонкости и неочевидные вещи, его определённо нужно комментировать.

Итого

Комментарии – важный признак хорошего разработчика, причём как их наличие, так и отсутствие.

Хорошие комментарии позволяют нам поддерживать код, дают возможность вернуться к нему после перерыва и эффективнее его использовать.

Комментируйте:

• Общую архитектуру, вид «с высоты птичьего полёта».
• Использование функций.
• Неочевидные решения, важные детали.

Избегайте комментариев:

• Которые объясняют, как работает код, и что он делает.
• Используйте их только в тех случаях, когда невозможно сделать настолько простой и самодокументированный код, что он не потребует комментариев.

Средства для генерации документации по коду, такие как JSDoc3, также используют комментарии: они их читают и генерируют HTML-документацию (или документацию в другом формате).

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

JavaScript комментарий можно использовать для объяснения кода JavaScript и сделать его более читабельным.

JavaScript комментарий также может использоваться для предотвращения выполнения при тестировании альтернативного кода.

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

Однострочные комментарии начинаются с // .

Любой текст между // и концом строки будет игнорироваться JavaScript (не будут выполнены).

В этом примере перед каждой строкой кода используется однострочный комментарий:

Пример

// Изменить заголовок:
document.getElementById(«myH»).innerHTML = «Моя первая страница»;

// Изменить параграф:
document.getElementById(«myP»).innerHTML = «Мой первый параграф.»;

В этом примере для объяснения кода используется однострочный комментарий в конце каждой строки:

Пример

var x = 5; // Объявите x, дайте ему значение 5
var y = x + 2; // Объявите y, дайте ему значение x + 2

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

Многострочные комментарии начинаются /* и заканчиваются */ .

Любой текст между /* и */ будет игнорироваться JavaScript.

В этом примере для объяснения кода используется многострочный комментарий (блок комментария):

Пример

/*
Приведенный ниже код изменится
заголовок с > и параграф с > на моей веб странице:
*/
document.getElementById(«myH»).innerHTML = «Моя первая страница»;
document.getElementById(«myP»).innerHTML = «Мой первый параграф.»;

Чаще всего используются однострочные комментарии.
Блочные комментарии часто используются для формальной документации.

Использование комментариев для предотвращения выполнения

Использование комментариев для предотвращения выполнения кода подходит для тестирования кода.

Добавление // перед строкой кода изменяет строки кода с исполняемой строки на комментарий.

В этом примере // используется для предотвращения выполнения одной из строк кода:

Пример

//document.getElementById(«myH»).innerHTML = «Моя первая страница»;
document.getElementById(«myP»).innerHTML = «Мой первый параграф.»;

В этом примере используется блок комментариев для предотвращения выполнения нескольких строк:

Пример

/*
document.getElementById(«myH»).innerHTML = «Моя первая страница»;
document.getElementById(«myP»).innerHTML = «Мой первый параграф.»;
*/

Мы только что запустили
SchoolsW3 видео

ВЫБОР ЦВЕТА

курс сегодня!

Сообщить об ошибке

Если вы хотите сообщить об ошибке или внести предложение, не стесняйтесь отправлять на электронное письмо:

Ваше предложение:

Спасибо Вам за то, что помогаете!

Ваше сообщение было отправлено в SchoolsW3.

ТОП Учебники

ТОП Справочники

ТОП Примеры

Получить сертификат

SchoolsW3 оптимизирован для бесплатного обучения, проверки и подготовки знаний. Примеры в редакторе упрощают и улучшают чтение и базовое понимание. Учебники, ссылки, примеры постоянно пересматриваются, чтобы избежать ошибок, но не возможно гарантировать полную правильность всего содержания. Некоторые страницы сайта могут быть не переведены на РУССКИЙ язык, можно отправить страницу как ошибку, так же можете самостоятельно заняться переводом. Используя данный сайт, вы соглашаетесь прочитать и принять Условия к использованию, Cookies и политика конфиденциальности.

Комментарии Javascript.

Как и любой другой язык программирования, язык Javascript поддерживает комментарии.

Т.е. комментарии — это некие символы (знаки), которые позволяют сделать так, чтобы какая-то часть кода не обрабатывалась браузером.

Если нам нужно вывести из действия какую-то строку кода, нам нужно перед этой строкой поставить 2 символа «//».

//console.log('123');

Это так называемый однострочный комментарий. С его помощью можно вывести из действия одну строку кода.

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

Пишется он следующим образом:

/* Комментарий */

Весь код, который находится внутри этой конструкции является комментарием и не обрабатывается браузером.

Зачем нам нужны комментарии?

1) Оперативно выводить из действия какой-либо кусок кода. Часто на практике нужно сделать так, чтобы часть кода временно не работала. Комментарии отлично подходят для решения этой задачи.

2) С помощью Javascript комментариев вы можете оставлять для себя какие-то заметки по ходу написания программы.

Бывает так, что сейчас вы помните, для чего вы пишите ту или иную часть кода, пройдет время и вы можете про это забыть.

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

Поработайте сейчас с этим элементом языка Javascript. Ничего сложного здесь нет. Думаю, что у вас все должно получиться.

Дмитрий Ченгаев ��
Занимаюсь заказной веб-разработкой. Подписывайтесь на телеграм канал https://t.me/dchengaev 😉
2020-12-29

Чтобы оставить сообщение, зарегистрируйтесь/войдите на сайт через: