Как эффективно использовать комментарии в JavaScript
Использование комментариев помогает понять код и его назначение. Однако многие разработчики не знают, как правильно использовать комментарии, а иногда и усложняют задачу.
Итак, в этой статье я расскажу, когда вам следует использовать комментарии, а также лучшие практики, которым вам нужно следовать.
В JavaScript есть 2 синтаксиса комментариев
Когда дело доходит до комментариев, каждый язык программирования имеет свой собственный набор синтаксиса. В JavaScript есть два синтаксиса, посвященных комментариям. Итак, прежде чем вдаваться в подробности, давайте быстро рассмотрим эти два синтаксиса.
1. Однострочные комментарии
В JavaScript однострочные комментарии начинаются с //. Он будет игнорировать все, что находится сразу после синтаксиса // до конца этой строки.
// Single line
Это также известно как встроенное комментирование, когда мы используем синтаксис // вместе со строками кода. Это наиболее точная форма комментария, поскольку она относится только к конкретной строке кода, на которой написана.
let p= 3.14; // The value of Pi (π) let a = 2 * p * 10 // Circumference of circle with radius 10
2. Многострочные комментарии.
Многострочные или блочные комментарии служат той же цели и, как следует из названия, расширяются на несколько строк.
Обычно большинство разработчиков используют синтаксис /* и */ для написания многострочных блочных комментариев. Но стандартный способ использования блочных комментариев в JavaScript:
- Начните с
/**в пустой строке. - Заканчивайте
*/в конечной строке. - Используйте
*в начале каждой строки между началом и концом.
/* Normal Multi-line Comment */ /** * Standard * Multi-line * Comment */
Когда следует использовать комментарии в JavaScript?
Как я уже упоминал, большую часть времени разработчики используют комментарии для объяснения кода. Но это еще не все.
1. Подготовка
Предисловие или объяснение кода - одна из основных целей использования комментариев. Это не только для других разработчиков; вам также может понадобиться обратиться к нему позже.
Вы можете использовать встроенные комментарии или использовать блочный комментарий с кратким объяснением его использования.
let result = getVisibleComponents(); // Retrieve UI components in Viewport
2. Для отладки
Поскольку движок JavaScript не интерпретирует закомментированные коды, мы можем использовать комментарии для целей отладки.
Например, если в вашем коде есть ошибка, вы можете закомментировать строки кода и повторно запустить код, чтобы увидеть, в какой строке я вызываю ошибку.
3. Добавление тегов
Использование тегов JSDocs - это еще один передовой опыт, которому команды разработчиков могут следовать, чтобы выражать свои идеи по коду членам команды.
Теги добавляют семантическую структуру вашим комментариям. Это, в свою очередь, позволяет инструментам разработки использовать эти данные для интеллектуального анализа.
/**
* @example
* // returns 6
* multiplication(2, 3);
* @example
* // returns -6
* @param {number} a - a number to multiply
* @param {number} b - a number to multiply
* multiplication(-2, 3);
*/
function multiplication(a, b) {
return a * b;
};
Точно так же вы можете использовать множество вариантов тегов, и эти теги дают четкое указание другим разработчикам, которые посещают вашу работу.
Bit, например, использует теги JSDocs для создания таблицы свойств компонентов:
4. Хранить метаданные
Еще одно распространенное использование комментариев - хранение метаданных файла. Например, мы можем включить в метаданные автора информации, версию, ссылки на репо, и они станут удобными в приложениях с открытым исходным кодом.
/** * @author Nipuni Arunodi * @version 0.0.1 * ... */
Примечание. Эти обычаи не определены и не зафиксированы. У разработчиков могут быть свои собственные практики, и я представил некоторые из наиболее часто используемых сценариев.
Рекомендации, которым следует следовать при использовании комментариев
Предварительно определенных правил использования комментариев нет. Но как отдельное лицо или группа, важно согласовать некоторые передовые практики в отношении комментариев для единообразия.
1. Код сообщает «как», а комментарии - «почему».
Комментарии должны быть информативными для человека, который их читает, и мы всегда должны избегать описания того, как работает код, в комментариях. Здесь код должен иметь возможность самостоятельно объяснять, как он работает, оставляя комментарии, чтобы выяснить, почему он вообще здесь.
// Do let p = 3.14; // Rounded value of Pi let c = 2 * p * 10; // Calculate the circumference of a circle with radius 10 // Don't let p = 3.14; // Initiate the value of the variable p let c = 2 * p * 10 // Multiply the value p into 20
2. Используйте только необходимый уровень детализации.
Комментарии - это хорошо. Однако не следует переусердствовать, описывая код сверх того, что требуется. Проблема здесь в том, что вам также необходимо поддерживать комментарии и изменять их. Кроме того, это может негативно повлиять на читабельность кода.
// Do
/**
* Retrieve a list users from the database
*/
async function getUsers() {
// ...
}
// Don't
/**
* Retrieve a list of user objects asynchronously by invoking a database query
*/
async function getUsers() {
// ...
}
3. Избегайте сокращений
Мы не должны использовать сокращения вроде aka, viz, потому что не все их понимают. Несмотря на то, что они делают ваши предложения короткими, они не позволяют донести ясное сообщение до читателя.
// Do /** * regEx, in other words Regular Expressions */ // Don't /** * regEx, viz. Regular Expressions
4. Используйте комментарии перед кодом.
Основная цель написания комментариев - дать читателям понять, чего они могут ожидать от нашего кода. Таким образом, они прочитают комментарии и поймут, что происходит, прежде чем изучать код.
Так что всегда полезно использовать комментарии над кодом, который вы объясняете, и это сэкономит много времени читателю.
/**
* Fetches articles of a writer based on writerId
* @param {string} writerId - The Id of the writer.
*/
function getArticles(writerId) {
// ...
}
5. Обратите особое внимание на числовые значения.
Работа с числовыми значениями всегда может быть сложной задачей, поскольку используются определенные диапазоны и единицы измерения. Здесь мы можем использовать комментарии, чтобы объяснить используемые единицы и их диапазоны. Также, если есть какие-либо ограничения на входные данные, мы можем упомянуть их в наших комментариях.
6. Воспользуйтесь поддержкой редактора
Все современные редакторы кода поддерживают использование комментариев. Итак, нам нужно получить от этого максимум.
Например, вы можете использовать ctrl + /, чтобы закомментировать одну строку кода или блок кода в любом редакторе. Кроме того, они автоматически завершают синтаксис блочного кода при вводе синтаксиса открытия (/**).
Кроме того, для VSCode доступны такие плагины, как Better Comments. Эти расширения помогают создавать более читаемые комментарии, как показано ниже:
Заключение
В этой статье я обсудил несколько вариантов использования комментариев в JavaScript и лучшие практики, которым мы должны следовать.
Как разработчики, мы всегда должны придерживаться этих передовых методов, поскольку это повысит удобочитаемость и упростит понимание вашего кода вам и вашей команде.
Я надеюсь, что эти предложения помогут вам улучшить читаемость вашего кода, и если у вас есть какие-либо предложения, поделитесь ими с другими в разделе комментариев.
Спасибо за чтение!!!
Создавайте лучшие библиотеки компонентов и системы проектирования
Делитесь компонентами между командами и проектами, чтобы ускорить разработку и убедиться, что ваши пользователи видят единообразный дизайн в каждой точке взаимодействия.
Инструменты OSS, такие как Bit, предлагают отличный опыт разработки для создания, совместного использования и внедрения компонентов в разных командах и приложениях. Создайте центр компонентов бесплатно попробуйте →
