Комментарии в html javascript

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

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

Инструкции

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

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

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

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

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

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

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

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

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

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

Код выведет 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( 'Мир' );

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

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

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

Источник

Комментарии

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

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

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

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

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

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

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

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

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

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

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.

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

 // Изменим заголовок: document.getElementById("myH").innerHTML = "Моя первая веб-страница"; // Изменим параграф: document.getElementById("myP").innerHTML = "Мой первый параграф."; 

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

 var x = 5; // Декларируем переменную x и присваиваем ей значение 5 var y = x + 2; // Декларируем переменную y и присваиваем ей значение x + 2 

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

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

В следующем примере используется многострочный комментарий (блок комментария) для пояснения 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 = "Мой первый параграф."; */ 

Источник