Какой правильный способ комментариев в 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: Комментарии

Кроме кода, в файлах с исходным кодом могут находиться комментарии. Это текст, который не является частью программы и нужен программистам для пометок. С их помощью добавляют пояснения, как работает код, какие здесь ошибки нужно поправить или не забыть что-то добавить позже.

// Удалить строку ниже после реализации задачи по регистрации console.log(10); 

Комментарии в JavaScript бывают двух видов:

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

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

Комментарий может занимать всю строчку. Если одной строчки мало, то создаются несколько комментариев:

// For Winterfell! // For Lanisters! 

Комментарий может находиться на строчке после какого-нибудь кода:

console.log('I am the King'); // For Lannisters! 

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

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

/* The night is dark and full of terrors. */ console.log('I am the King'); 

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

Задание

Создайте однострочный комментарий с текстом: You know nothing, Jon Snow! .

Упражнение не проходит проверку — что делать? ��

Если вы зашли в тупик, то самое время задать вопрос в «Обсуждениях». Как правильно задать вопрос:

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

В моей среде код работает, а здесь нет ��

Тесты устроены таким образом, что они проверяют решение разными способами и на разных данных. Часто решение работает с одними входными данными, но не работает с другими. Чтобы разобраться с этим моментом, изучите вкладку «Тесты» и внимательно посмотрите на вывод ошибок, в котором есть подсказки.

Мой код отличается от решения учителя ��

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

В редких случаях бывает, что решение подогнано под тесты, но это видно сразу.

Прочитал урок — ничего не понятно ��

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

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

Полезное

Определения

• Комментарий — текст в коде программы, который не влияет на функциональность и добавляется программистами для себя и своих коллег. // однострочный комментарий

/* многострочный комментарий многострочный комментарий */ 

Комментарии

Порой при написании кода вам необходимо будет снабдить его пояснениями, предназначенными только для людей , а не для компьютера. Возможно, это будет некое послание к себе из прошлого (к Будущему Мне!) по поводу той или иной вещи в программном коде. А может, это будет просто указание, что запустить нужно лишь такую-то часть кода, а прочее надлежит опустить. Словом, в любом подобном случае вам необходимо будет прибегнуть к помощи комментариев. Комментарии используются для добавления ➕ подсказок, заметок , предложений или предупреждений. Они могут упростить чтение и понимание �� кода. Также они могут быть использованы для предотвращения выполнения кода (этот приём практикуется при отладке кода).

В JavaScript есть несколько способов указать комментарии в коде.

Видео​

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

Первый 1️⃣ способ // комментарий в этом случае весь текст в строке после двойного слэша будет комментарием . Когда интерпретатор видит два 2️⃣ слэша подряд // , он сразу понимает, что всё, что идёт далее до конца строки, можно смело проигнорировать. Пока не обращайте внимание на синтаксис кода, с ним мы детально познакомимся чуть позже.

Интерактивный редактор

function learnJavaScript()  
 
// Это комментарий в строке 
 
var hello = 'Hello world. ' 
 
return hello
 
>

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

Второй 2️⃣ способ — это /* */ , такой способ более гибок, чем первый 1️⃣ . Как только интерпретатор видит /* , он думает: «Ага, значит, пока я не увижу */ , то могу ни на что здесь не обращать никакого внимания!» Например, вы можете использовать его в одной 1️⃣ строке :

Интерактивный редактор

function learnJavaScript()  
 
/* Это однострочный комментарий */ 
 
var hello = 'Hello world. ' 
 
return hello
 
>

Либо вы можете сделать многострочный комментарий , как показано здесь :

Интерактивный редактор

function learnJavaScript()  
 
/*Этот комментарий располагается на нескольких линиях. 
 Обратите внимание, что вам не нужно обрывать комментарий, пока вы его не закончите*/ 
 
var hello = 'Hello world. ' 
 
/* Напишите здесь свой комментарий */ 
 
return hello
 
>

Комментарий посреди кода​

Также, если пожелаете, то вы можете использовать такое комментирование посреди строки кода. Хотя это может ухудшить читабельность кода :

Интерактивный редактор

function learnJavaScript()  
 
var x = '' 
 
var hello = 'Hello ' + x /* вставьте значение x */ + '!' 
 
return hello
 
>

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

Это не только облегчает понимание нашего кода, но и помогает улучшить общий дизайн программы!

Этот тип кода часто называют самодокументированием.

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

С комментированием кода все и прозвучал звонок на перемену .

React Native​

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

Проблемы?​

Пишите в Discord или телеграмм чат, а также подписывайтесь на наши новости

Вопросы:​

Для кого предназначены комментарии?

1. Человек
2. Консоль
3. Интерпретатор JavaScript

Для чего используются комментарии?

1. Добавление подсказок, заметок, предложений
2. Для выполнения запросов
3. Для предотвращения выполнения кода

Какого из способов указания комментария в коде JavaScript не существует?

Как отключить любое количество строк кода?

1. Написать комментарий посреди кода
2. Обернуть код в комментарий
3. Использовать команду console.log

Интерпретатор JavaScript _ _ _ _ любые найденные комментарии.

1. Выполняет
2. Игнорирует
3. Компилирует

Какой символ обозначает однострочный комментарий?

Какие символы необходимо ввести, чтобы начать комментарий блока?

Какой термин относится к коду, который имеет полезные имена переменных и описательных имен функций, чтобы разработчику было легко понять цель кода, когда он его читает (без особой необходимости в пояснительных комментариях)?

1. Самодокументирование
2. Документирование
3. Рукопись

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

Ссылки:​

1. MDN web docs
2. Код для подростков: прекрасное руководство по программированию для начинающих, том 1: Javascript — Jeremy Moritz
3. JavaScript.ru

Contributors ✨​

Thanks goes to these wonderful people (emoji key):

Hello, World! — Основы JavaScript

По традиции начнем с написания программы «Hello, World!». Эта программа будет выводить на экран текст. Чтобы вывести что-то на экран, нужно дать компьютеру специальную команду. В языке JavaScript такая команда — console.log() :

console.log('Hello, World!'); // => Hello, World! 

Иногда для удобства мы будем показывать в комментариях результат запуска строчек кода, вот так: => РЕЗУЛЬТАТ . Например, // => 4 .

Комментарии

Кроме собственного кода в файлах с исходным кодом могут находиться комментарии. Это текст, который не является частью программы и нужен программистам для пометок. С их помощью добавляют пояснения, как работает код, какие здесь ошибки нужно поправить или не забыть что-то добавить позже.

// Удалить строку ниже после реализации задачи по регистрации console.log(10); 

Комментарии в JavaScript бывают двух видов.

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

// For Winterfell! // For Lanisters! 

Комментарий может находиться на строке после какого-нибудь кода:

console.log('I am the King'); // For Lannisters! 

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

/* The night is dark and full of terrors. */ console.log('I am the King'); 

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

Дополнительные материалы

Остались вопросы? Задайте их в разделе «Обсуждение»

Вам ответят команда поддержки Хекслета или другие студенты

Об обучении на Хекслете

• Статья «Как учиться и справляться с негативными мыслями»
• Статья «Ловушки обучения»
• Статья «Сложные простые задачи по программированию»
• Урок «Как эффективно учиться на Хекслете»
• Вебинар « Как самостоятельно учиться »

Открыть доступ

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

• 130 курсов, 2000+ часов теории
• 1000 практических заданий в браузере
• 360 000 студентов

Наши выпускники работают в компаниях: