node js комментарии в коде
JavaScript. Комментарии (однострочные, многострочные, теги)
Комментарии в JavaScript. Однострочные и многострочные комментарии. Теги, применяемые для выделения комментариев в зависимости от количества строк.
Однострочные комментарии в JavaScript
Чтобы закомментировать одну строку в коде JavaScript, перед ней необходимо вставить одиночный (непарный) тег в виде двух наклонных линий (двойной слэш): //.
Однострочный комментарий можно вставлять в конце строки с кодом:
Многострочные комментарии в JavaScript
Для выделения многострочных комментариев используются двойные (парные) теги: открывающий: /* и закрывающий: */.
Или так, для большей наглядности:
Используйте комментирование строк в JavaScript не только исключительно для написания комментариев, но и для отключения участков кода при отладке программ.
Комментарии в программировании — это пояснения к исходному тексту программы, которую вы пишете. Находятся они внутри комментируемого кода. Некоторые специалисты считают, что если для понимания программы требуются комментарии, значит, она плохо написана. Другие считают, что надо всегда комментировать свой код, и не только тот, который пишется для других, но и тот, который пишется для себя. Если первое время кажется, что прекрасно помнишь внутреннюю структуру и принцип работы своего кода, через неделю-две уже бывает трудно разобраться, а еще через какое-то время смотришь на свою программу, как на чужую. Чтобы этого не случилось и можно было быстро восстановить в памяти предыдущий ход мыслей, необходимо пошаговое комментирование своих действий.
Добавить комментарий Отменить ответ
Представленная на сайте информация носит справочный характер и не является публичной офертой.
Комментарии Javascript
Комментарии используются для пояснения JavaScript кода, чтобы сделать его более понятным.
Также, комментарии позволяют закрыть отдельные участки JavaScript кода от выполнения во время тестирования альтернативных алгоритмов.
Однострочные комментарии
Чтобы определить однострочный комментарии, необходимо перед текстом комментария написать двойной прямой слэш (//). Любой текст между двойным слэшем (//) и концом строки будет игнорироваться (не будет выполняться) обработчиком JavaScript.
В следующем примере перед каждой строкой кода определяется однострочный комментарий:
В следующем примере одностроччный комментарий используется в конце каждой строки для пояснения JavaScript кода:
Многострочные комментарии
Для определения многострочного комментария используется конструкция /*. */. Любой текст, находящийся между /* и */ будет игнорироваться обработчиком JavaScript.
В следующем примере используется многострочный комментарий (блок комментария) для пояснения JavaScript кода:
Как правило, чаще используют однострочные комментарии. Блоки комментариев обычно используются для официальной документации.
Использование комментариев, чтобы закрыть код от выполнения
Для того чтобы протестировать работу скрипта, очень удобно закрывать определенные участки кода при помощи комментариев, проверяя различные альтернативы.
Добавление слэшей // перед строкой кода сделает его неисполняемым и превратит в комментарий.
В следующем примере слэши // используются, чтобы закрыть от выполнения одну из строк кода:
В следующем примере блок комментариев используется, чтобы закрыть от выполнения сразу несколько строк кода:
Комментарии
Обычно мы их используем, чтобы описать, как и почему работает код.
На первый взгляд, в комментариях нет ничего сложного, но новички в программировании часто применяют их неправильно.
Плохие комментарии
Новички склонны использовать комментарии, чтобы объяснять, «что делает код». Например, так:
Но в хорошем коде количество «объясняющих» комментариев должно быть минимальным. Серьёзно, код должен быть таким, чтобы его можно было понять без комментариев.
Про это есть хорошее правило: «Если код настолько запутанный, что требует комментариев, то, может быть, его стоит переделать?»
Рецепт: выносите код в функции
Иногда выгодно заменить часть кода функцией, например, в таком случае:
Лучший вариант – использовать отдельную функцию isPrime :
Теперь код легче понять. Функция сама становится комментарием. Такой код называется самодокументированным.
Рецепт: создавайте функции
И если мы имеем такой длинный кусок кода:
То будет лучше отрефакторить его с использованием функций:
Здесь комментарии тоже не нужны: функции сами говорят, что делают (если вы понимаете английский язык). И ещё, структура кода лучше, когда он разделён на части. Понятно, что делает каждая функция, что она принимает и что возвращает.
В реальности мы не можем полностью избежать «объясняющих» комментариев. Существуют сложные алгоритмы. И есть хитрые уловки для оптимизации. Но в целом мы должны стараться писать простой и самодокументированный код.
Хорошие комментарии
Итак, обычно «объясняющие» комментарии – это плохо. Но тогда какой комментарий считается хорошим?
Сделайте высокоуровневый обзор компонентов, того, как они взаимодействуют, каков поток управления в различных ситуациях… Если вкратце – обзор кода с высоты птичьего полёта. Существует специальный язык UML для создания диаграмм, разъясняющих архитектуру кода. Его определённо стоит изучить.
Документируйте параметры и использование функций
Есть специальный синтаксис JSDoc для документирования функций: использование, параметры, возвращаемое значение.
Подобные комментарии позволяют нам понимать назначение функции и правильно её использовать без необходимости заглядывать в код.
Кстати, многие редакторы, такие как WebStorm, прекрасно их распознают для того, чтобы выполнить автодополнение ввода и различные автоматические проверки кода.
Также существуют инструменты, например, JSDoc 3, которые умеют генерировать HTML-документацию из комментариев. Получить больше информации о JSDoc вы можете здесь: http://usejsdoc.org/.
Почему задача решена именно таким способом?
Важно то, что написано. Но то, что не написано, может быть даже более важным, чтобы понимать происходящее. Почему задача решена именно этим способом? Код не даёт ответа.
Если есть несколько способов решить задачу, то почему вы выбрали именно этот? Особенно если ваш способ – не самый очевидный.
Без подобных комментариев возможна следующая ситуация:
Комментарии, объясняющие решение, очень важны. Они помогают продолжать разработку в правильном направлении.
В коде есть какие-то тонкости? Где они используются?
Если в коде есть какие-то тонкости и неочевидные вещи, его определённо нужно комментировать.
Итого
Комментарии – важный признак хорошего разработчика, причём как их наличие, так и отсутствие.
Хорошие комментарии позволяют нам поддерживать код, дают возможность вернуться к нему после перерыва и эффективнее его использовать.
Комментируйте:
Избегайте комментариев:
Средства для генерации документации по коду, такие как JSDoc3, также используют комментарии: они их читают и генерируют HTML-документацию (или документацию в другом формате).
Руководство для начинающих в Node.js
Автором было замечено множество комментариев в духе “я скачал/скачала Node.js, и что теперь?”. Этот урок отвечает на данный вопрос и объясняет новичку, с чего начать.
Что такое Node.js?
Очень много путаницы у новичков из-за непонимания того, что такое Node.js. И даже описание с официального сайта не помощник.
Важную вещь, которую нужно осознать — Node не является веб-сервером. Сама по себе платформа ничего не делает. Она не работает как Apache. Нет конфигурационных файлов, в которых она указывает вам на HTML-файлы. Если вы хотите, чтобы платформа была HTTP-сервером, вам придётся написать HTTP-сервер (с помощью встроенных библиотек).
Node.js — это просто другой способ выполнять код на вашем компьютере. Это среда выполнения языка JavaScript.
Устанавливаем Node
Node.js легко установить. Достаточно зайти на страницу загрузки официального сайта.
Я установил, и что теперь?
После установки у вас появилась новая команда в командной строке “node”. Вы можете использовать Node двумя способами.
Итак, создаем файл:
hello.js
И сохраняем его в директорию, из которой будем запускать этот файл. Чтобы перейти достаточно в командной строке написать cd полное_название_директории (ну или можно использовать относительную адресацию, о которой можно почитать здесь.
Запускаем в командной строке:
В данном случае мы переместили сообщение файла console.log и отправили этот файл команде node как аргумент. Node запускает код JavaScript в файле и распечатывает “Hello World”.
Файлы ввода/вывода с node.js
Запуск чистого JavaScript — это здорово, но не очень полезно. Поэтому в Node.js есть огромное количество библиотек (модулей) для того, чтобы делать реальные вещи. В данном примере мы откроем файл с записями и будем его обрабатывать.
example_log.txt
Что означает этот файл, не так важно, но нужно знать, что каждая запись содержит дату, букву и значение. Мы хотим соотнести каждую букву с соответствующим значением.
Нам нужно считать содержание файла.
my_parser.js
К счастью, Node.js сильно облегчает обработку содержания файла с помощью встроенного модуля filesystem (fs). Модуль fs имеет функцию readFile, которая берёт путь к файлу и обратный вызов. Обратный вызов будет исполнен, когда файл будет полностью прочитан. Данные файла попадают в форме типа Buffer, что является набором битов. Мы можем конвертировать в строку с помощью функции toString()
Теперь добавим парсировщик (он написан на чистом JavaScript).
my_parser.js
Когда файл будет аргументом команды node, результат распечатается, и будет осуществлён выход.
Асинхронные вызовы в node.js
Как вы заметили в прошлом примере, для Node.js характерно использование асинхронных вызовов. По существу вы пишете, что нужно делать, и когда это будет сделано, будет вызван обратный вызов, потому что node.js однопоточен. Пока вы ждёте запуска обратного вызова, Node.js может уйти и делать другие вещи вместо блокировки до завершения запроса.
Это особенно важно для веб-серверов. Довольно характерно для современных веб-приложений иметь доступ к базам данных. Пока вы ждёте возвращения результата от базы данных, Node может обрабатывать больше запросов. Это позволяет справляться с тысячами параллельных запросов с маленькими накладными расходами по сравнению с созданием отдельного потока для каждого соединения.
Создание веб-сервера с помощью node.js
Как было уже сказано, Node ничего не может делать сам по себе. Один из встроенных модулей позволяет легко создать простой HTTP сервер, пример его использования приведен на главной странице официального сайта.
mywebserver.js
Ещё раз: это базовый веб-сервер, а не сервер с полным функционалом. Он не может обслуживать картинки или HTML-файлы. На самом деле, какой бы вы ни отправили запрос, он возвратит “Hello World”. Однако, вы можете запустить этот скрипт, перейти по адресу http://localhost:8080 в своем браузере и увидеть этот текст.
Вы уже могли заметить, что ваше приложение на node.js больше не останавливается. Всё потому, что вы создали веб-сервер, и ваше приложение на node.js отвечает на запросы до тех пор, пока вы сами его не остановите.
Если вы хотите сделать веб-сервер с полной функциональностью, вам придётся проделать некоторый объем работы: нужно будет проверить все запросы, считать подходящие файлы и отправить вывод обратно. Есть и хорошие новости. Люди уже проделали эту тяжелую работу за вас.
Модуль Express для node.js
Express — это фреймворк, который облегчит создание большинства обычных сайтов. Сперва вам будет необходимо установить его. Вместе с командой node у вас будет доступ к команде “npm”. Этот инструмент даёт доступ к огромному количеству модулей, созданных сообществом, в том числе и Express.
Когда вы установите модуль, он будет положен в папку node_modules в директории вашего приложения. Теперь вы сможете использовать его функциональность так, как будто он встроен.
Давайте создадим базовый статический сервер с использованием Express.
mystaticfile_server.js
Теперь у вас есть довольно умелый статический файловый сервер. Всё, что вы положили в папку public, может быть запрошено и показано браузером: HTML, картинки, почти всё, что угодно. Так, например, если вы положите картинку под названием “my_image.png” внутрь папки public, вы можете открыть картинку прямо в браузере, перейдя по адресу http://localhost:8080/my_image.png. Конечно, Express имеет довольно обширную функциональность, и вы можете изучить её в ходе разработки.
Мы чуть-чуть затронули NPM в предыдущей секции, но мы хотели бы подчеркнуть, как важен этот инструмент при обычной разработке в Node.js. Тысячи модулей доступны для решения почти всех типичных проблем, с которыми вы, вероятно, можете столкнуться. Помните, что стоит проверить NPM прежде, чем изобретать велосипед. Для типичного приложения на node.js характерно иметь множество подключенных модулей.
В предыдущем примере мы вручную установили Express. Если у вас много подключенных библиотек, устанавливать их все вряд ли будет хорошей затеей. Поэтому npm использует файл package.json.
package.json
Файл package.json содержит обзор вашего приложения. Здесь много доступных полей, но представлен необходимый минимум. Секция “dependency” описывает название и версию модулей, которые вы бы хотели установить. В данном случае мы принимаем любую версию Express.3.3. В данной секции вы можете перечислить столько библиотек, сколько вам угодно.
Теперь вместо того, чтобы устанавливать каждую библиотеку отдельно, мы можем запустить одну команду и установить всё необходимое одним махом.
Когда вы запустите команду, npm будет искать в текущей папке файл package.json. Если найдет, то установит каждую библиотеку из списка.
Организация кода в node.js
До сих пор мы использовали один файл, но так очень тяжело обслуживать проект. В большинстве приложений ваш код будет находиться в нескольких файлах. Здесь нет стандартной или принудительной организации того, какие файлы куда идут. Это не Rails. Вы делаете то, что вам хочется.
Давайте реорганизуем скрипт, обрабатывающий файл с записями. Впоследствии будет намного легче тестировать и обслуживать, если мы поместим логику разбора в отдельный файл.
parser.js
То, что мы сделали, было созданием нового файла, содержащего логику для обработки записей. Это только стандартный код JavaScript, и существует множество способов внедрить этот код. Мы выбрали то, как определить новый объект JavaScript, и его легко модульно протестировать.
Важной строчкой является “module.exports”. Это пояснение для Node, что вы экспортируете из этого файла. В данном случае я экспортирую конструктор, поэтому пользователи могут создавать экземпляры моего объекта типа Parser. Вы можете экспортировать, что захотите.
Так как мы экспортировали конструктор, то это то, что будет возвращено из запроса. Теперь мы можем создавать экземпляры объектов типа Parser и использовать их.
Вы когда-нибудь возвращались к проекту и испытывали трудности с пониманием внутренней логики? Вероятно, это потому, что указанный проект не был прокомментирован должным образом.
В этой статье мы рассмотрим, как комментировать код JavaScript, какие типы комментариев существуют, а также некоторые передовые практики.
Однострочные комментарии
Давайте посмотрим на пример однострочного комментария в действии:
Здесь мы используем однострочный комментарий, чтобы описать, что делает следующая строка кода.
Если однострочный комментарий появляется в конце строки кода, он называется встроенным комментарием.
Обычно они используются для добавления быстрых аннотаций:
Многострочные комментарии и строки документации JavaScript
Если мы хотим добавить примечание, которое занимает несколько строк, мы можем выбрать многострочные комментарии или комментарии на уровне блока.
Многострочные комментарии начинаются /* и заканчиваются */ :
Здесь многострочный комментарий используется для описания крестиков-ноликов. Как правило, многострочные комментарии используются для введения и объяснения раздела кода, где одной строки / предложения недостаточно.
Часто можно увидеть и другой тип многострочного комментария:
Часто эти комментарии могут включать информацию о выполняемом коде, такую как параметры функции или даже автора кода:
Эти комментарии называются DocStrings, поскольку они по сути являются строками (комментариями), составляющими документацию вашего кода.
Эти типы комментариев действительно полезны для других разработчиков в вашей команде, так как вы можете уточнить, каковы ожидаемые входные данные, каковы выходные данные, а также к кому обращаться в случае необходимости.
Дополнительным преимуществом является то, что вы можете создавать документацию на основе этих строк документа.
Использование комментариев для отладки
Помимо заметок, комментарии также можно использовать для быстрого предотвращения выполнения кода в целях отладки. Это возможно, потому что движки JavaScript не интерпретируют закомментированный код.
Если есть ошибочная строка, которая вызывает проблемы, мы можем просто «закомментировать ее», чтобы отключить ее, не удаляя строку. Это может быть связано с реальными отладчиками, чтобы помочь вам оценить, что происходит.
Рассмотрим следующий код:
Если мы хотим удалить второй оператор, но не хотим удалять его навсегда, мы можем просто закомментировать его:
Совет: в большинстве редакторов кода мы можем использовать сочетание клавиш Ctrl + / для Windows и Cmd + / для Mac, чтобы закомментировать одну строку кода.
Кроме того, вы также можете закомментировать целые разделы, если не уверены, удалять ли их или нет:
Хорошие практики комментирования
Используйте комментарии, чтобы объяснить, почему вы что-то сделали, а не как вы это сделали. Если вы обнаружите, что объясняете, как вы что-то сделали, то пора сделать шаг назад и реорганизовать ваш код в нечто самоочевидное.
Существуют полезные инструменты, такие как JSDOC 3, которые могут создавать документацию только на основе комментариев в вашем коде, которые отформатированы как DocStrings, описанные выше.
Вывод
Мы также увидели, как отлаживать наш код, используя технику, называемую «комментирование», и, наконец, подытожили некоторые хорошие практики комментирования.