Как делать комментарии в javascript
Перейти к содержимому

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

  • автор:

Структура кода

Начнём изучение языка с рассмотрения основных «строительных блоков» кода.

Инструкции

Инструкции – это синтаксические конструкции и команды, которые выполняют действия.

Мы уже видели инструкцию alert(‘Привет, мир!’) , которая отображает сообщение «Привет, мир!».

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

Например, здесь мы разделили сообщение «Привет Мир» на два вызова alert:

alert('Привет'); alert('Мир');

Обычно каждую инструкцию пишут на новой строке, чтобы код было легче читать:

alert('Привет'); alert('Мир');

Точка с запятой

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

Так тоже будет работать:

alert('Привет') alert('Мир')

В этом случае JavaScript интерпретирует перенос строки как «неявную» точку с запятой. Это называется автоматическая вставка точки с запятой.

В большинстве случаев новая строка подразумевает точку с запятой. Но «в большинстве случаев» не значит «всегда»!

В некоторых ситуациях новая строка всё же не означает точку с запятой. Например:

alert(3 + 1 + 2);

Код выведет 6 , потому что JavaScript не вставляет здесь точку с запятой. Интуитивно очевидно, что, если строка заканчивается знаком «+» , значит, это «незавершённое выражение», поэтому точка с запятой не требуется. И в этом случае всё работает, как задумано.

Но есть ситуации, где JavaScript «забывает» вставить точку с запятой там, где она нужна.

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

Пример ошибки

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

alert('Hello'); [1, 2].forEach(alert);

Пока нет необходимости знать значение скобок [] и forEach . Мы изучим их позже. Пока что просто запомните результат выполнения этого кода: выводится Hello , затем 1 , затем 2 .

А теперь давайте уберем точку с запятой после alert :

alert('Hello') [1, 2].forEach(alert);

Этот код отличается от кода, приведенного выше, только в одном: пропала точка с запятой в конце первой строки.

Если мы запустим этот код, выведется только первый alert , а затем мы получим ошибку (вам может потребоваться открыть консоль, чтобы увидеть её)!

Это потому что JavaScript не вставляет точку с запятой перед квадратными скобками [. ] . И поэтому код в последнем примере выполняется, как одна инструкция.

Вот как движок видит его:

alert('Hello')[1, 2].forEach(alert);

Выглядит странно, правда? Такое слияние в данном случае неправильное. Мы должны поставить точку с запятой после alert , чтобы код работал правильно.

Это может произойти и в некоторых других ситуациях.

Мы рекомендуем ставить точку с запятой между инструкциями, даже если они отделены переносами строк. Это правило широко используется в сообществе разработчиков. Стоит отметить ещё раз – в большинстве случаев можно не ставить точку с запятой. Но безопаснее, особенно для новичка, ставить её.

Комментарии

Со временем программы становятся всё сложнее и сложнее. Возникает необходимость добавлять комментарии, которые бы описывали, что делает код и почему.

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

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

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

// Этот комментарий занимает всю строку alert('Привет'); alert('Мир'); // Этот комментарий следует за инструкцией

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

/* Пример с двумя сообщениями. Это - многострочный комментарий. */ alert('Привет'); alert('Мир');

Содержимое комментария игнорируется, поэтому, если мы поместим код внутри /* … */ , он не будет исполняться.

Это бывает удобно для временного отключения участка кода:

/* Закомментировали код alert('Привет'); */ alert('Мир');

Используйте горячие клавиши!

В большинстве редакторов строку кода можно закомментировать, нажав комбинацию клавиш Ctrl + / для однострочного комментария и что-то вроде Ctrl + Shift + / – для многострочных комментариев (выделите кусок кода и нажмите комбинацию клавиш). В системе Mac попробуйте Cmd вместо Ctrl и Option вместо Shift .

Вложенные комментарии не поддерживаются!

Не может быть /*. */ внутри /*. */ .

Такой код «умрёт» с ошибкой:

/* /* вложенный комментарий . */ */ alert( 'Мир' );

Не стесняйтесь использовать комментарии в своём коде.

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

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

Комментирование кода в JavaScript — типы и передовые методы

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

Вы когда-нибудь возвращались к проекту и испытывали трудности с пониманием внутренней логики? Вероятно, это потому, что указанный проект не был прокомментирован должным образом.

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

В этой статье мы рассмотрим, как комментировать код JavaScript, какие типы комментариев существуют, а также некоторые передовые практики.

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

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

Давайте посмотрим на пример однострочного комментария в действии:

// Print "Hello World" in the console console.log("Hello World"); 

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

Если однострочный комментарий появляется в конце строки кода, он называется встроенным комментарием.

Обычно они используются для добавления быстрых аннотаций:

let c = a + b; // Assign sum of a, b to c 

Многострочные комментарии и строки документации JavaScript

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

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

/* The following program contains source code for a game called Tic-tac-toe. It is a paper-and-pencil game for two players, X and O, who take turns marking the spaces in a 3×3 grid. The player who succeeds in placing three of their marks in a horizontal, vertical, or diagonal row is the winner */ 

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

Часто можно увидеть и другой тип многострочного комментария:

/** * The following program contains source code for a game called Tic-tac-toe. * It is a paper-and-pencil game for two players, X and O, who take turns marking the * spaces in a 3×3 grid. * The player who succeeds in placing three of their marks in a horizontal, vertical, or * diagonal row is the winner */ 

Часто эти комментарии могут включать информацию о выполняемом коде, такую ​​как параметры функции или даже автора кода:

/** * Function that greets a user * @author John * @param name Name of the user * @return Greeting message */ function greetUser(name) < return `Greetings, $!`; > 

Эти комментарии называются DocStrings, поскольку они по сути являются строками (комментариями), составляющими документацию вашего кода.

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

Дополнительным преимуществом является то, что вы можете создавать документацию на основе этих строк документа.

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

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

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

Рассмотрим следующий код:

console.log("Working code"); console.log("Erroneous code); 

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

console.log("Working code"); //console.log("Erroneous code); 

Совет: в большинстве редакторов кода мы можем использовать сочетание клавиш Ctrl + / для Windows и Cmd + / для Mac, чтобы закомментировать одну строку кода.

Кроме того, вы также можете закомментировать целые разделы, если не уверены, удалять ли их или нет:

/*console.log("Entering for loop"); for (let i = 0; i < 100; i++) < console.log(i); >*/ 

Хорошие практики комментирования

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

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

Еще один совет — не писать очевидные и излишние комментарии. Например, совершенно не нужен следующий комментарий:

// Prints out the result console.log(result) 

Существуют полезные инструменты, такие как JSDOC 3, которые могут создавать документацию только на основе комментариев в вашем коде, которые отформатированы как DocStrings, описанные выше.

Вывод

В этой статье мы рассмотрели, что такое комментарии и как их создавать в JavaScript. Мы рассмотрели различные типы комментариев — однострочные и многострочные комментарии, а также строки документации JavaScript.

Мы также увидели, как отлаживать наш код, используя технику, называемую «комментирование», и, наконец, подытожили некоторые хорошие практики комментирования.

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 видео

ВЫБОР ЦВЕТА

colorpicker

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

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

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

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

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

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

ТОП Учебники
ТОП Справочники
ТОП Примеры
Получить сертификат

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

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! .

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

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

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

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

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

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

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

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

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

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

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

Полезное

Определения

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

Добавить комментарий

Ваш адрес email не будет опубликован. Обязательные поля помечены *