Какой правильный способ комментариев в javascript

Комментарии

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

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

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

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

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

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

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

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

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

Лучший вариант – использовать отдельную функцию isPrime :

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

Рецепт: создавайте функции

И если мы имеем такой длинный кусок кода:

То будет лучше отрефакторить его с использованием функций:

Здесь комментарии тоже не нужны: функции сами говорят, что делают (если вы понимаете английский язык). И ещё, структура кода лучше, когда он разделён на части. Понятно, что делает каждая функция, что она принимает и что возвращает.

В реальности мы не можем полностью избежать «объясняющих» комментариев. Существуют сложные алгоритмы. И есть хитрые уловки для оптимизации. Но в целом мы должны стараться писать простой и самодокументированный код.

Хорошие комментарии

Итак, обычно «объясняющие» комментарии – это плохо. Но тогда какой комментарий считается хорошим?

Описывайте архитектуру Сделайте высокоуровневый обзор компонентов, того, как они взаимодействуют, каков поток управления в различных ситуациях… Если вкратце – обзор кода с высоты птичьего полёта. Существует специальный язык UML для создания диаграмм, разъясняющих архитектуру кода. Его определённо стоит изучить. Документируйте параметры и использование функций Есть специальный синтаксис JSDoc для документирования функций: использование, параметры, возвращаемое значение.

Подобные комментарии позволяют нам понимать назначение функции и правильно её использовать без необходимости заглядывать в код.

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

Также существуют инструменты, например, JSDoc 3, которые умеют генерировать HTML-документацию из комментариев. Получить больше информации о JSDoc вы можете здесь: https://jsdoc.app.

Почему задача решена именно таким способом?

Важно то, что написано. Но то, что не написано, может быть даже более важным, чтобы понимать происходящее. Почему задача решена именно этим способом? Код не даёт ответа.

Если есть несколько способов решить задачу, то почему вы выбрали именно этот? Особенно если ваш способ – не самый очевидный.

Без подобных комментариев возможна следующая ситуация:

1. Вы (или ваш коллега) открываете написанный некоторое время назад код и видите, что в нём есть, что улучшить.
2. Вы думаете: «Каким глупым я раньше был и насколько умнее стал сейчас», и переписываете его на «более правильный и оптимальный» вариант.
3. …Желание переписать код – это хорошо. Но в процессе вы понимаете, что «оптимальное» решение на самом деле не такое уж и оптимальное. Вы даже смутно припоминаете, почему, так как в прошлый раз вы уже его пробовали. Вы возвращаетесь к правильному варианту, потратив время зря.

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

В коде есть какие-то тонкости? Где они используются?

Если в коде есть какие-то тонкости и неочевидные вещи, его определённо нужно комментировать.

Итого

Комментарии – важный признак хорошего разработчика, причём как их наличие, так и отсутствие.

Хорошие комментарии позволяют нам поддерживать код, дают возможность вернуться к нему после перерыва и эффективнее его использовать.

Комментируйте:

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

Избегайте комментариев:

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

Средства для генерации документации по коду, такие как JSDoc3, также используют комментарии: они их читают и генерируют HTML-документацию (или документацию в другом формате).

JavaScript Комментарии

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

Комментарии в JavaScript также можно использовать для предотвращения выполнения при тестировании альтернативного кода.

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

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

Любой текст между // и концом строки будет игнорироваться JavaScript (не будет выполнен).

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

Пример

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

// Изменить параграф:
document.getElementById("myP").innerHTML = "Мой первый параграф.";

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

Пример

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

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

Любой текст между /* и */ будет игнорироваться JavaScript.

В этом примере для объяснения кода используется многострочный комментарий (блок комментария):

Пример

Чаще всего используются однострочные комментарии.
Блочные комментарии часто используются для формальной документации.

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

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

Добавление // перед строкой кода изменяет строки кода с исполняемой строки на комментарий.

В этом примере // используется для предотвращения выполнения одной из строк кода:

Пример

В этом примере используется блок комментария для предотвращения выполнения нескольких строк:

Пример

ПАЛИТРА ЦВЕТОВ

ПРИСОЕДИНЯЙТЕСЬ!

Связь с админом

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

Топ Учебники

Топ Справочники

Топ Примеры

Веб Сертификаты

Этот сайт оптимизирован для обучения и тестирования. Примеры могут быть упрощены для улучшения чтения и базового понимания. Учебные пособия, ссылки и примеры постоянно пересматриваются, чтобы избежать ошибок, но мы не можем гарантировать полную правильность и работоспособность всего контента. Используя этот сайт, вы соглашаетесь с тем, что прочитали и приняли условия использования, cookie и политику конфиденциальности.
Также вы можете абсолютно бесплатно скачать офлайн версию сайта W3Schools на русском архивом с GitHub и пользоваться локально на своём компьютере.
Также доступна версия сайта W3Schools на украинском языке.
Copyright 1999-2023 by Refsnes Data. All Rights Reserved.
Сайт работает на фреймворке W3.CSS.

Правила оформления JavaScript-кода

Для создания объекта используйте фигурные скобки. Не создавайте объекты через конструктор new&nbspObject .

1.2 Зарезервированные слова

Не используйте зарезервированные слова в качестве ключей объектов. Они не будут работать в IE8.

1.3 Ключевые слова

Не используйте ключевые слова (в том числе измененные). Вместо них используйте синонимы.

1.4 Создание обьекта на 3 и более элементов.

При создании обьектов, равно как и массивов, содержащих большое количество свойств(элементов), и тем самым образующих строки, длиной более 20 символов, необходимо выполнять ряд условий:

• Открывающая скобка располагается на той же строке;
• Каждое свойство оформляется на новой строке;
• Пробел после двоеточия;
• Закрывающая скобка располагается на новой строке.

2. Переменные

Для именования переменных используйте существительные на английском языке(не транслит!). Имя переменной должно быть осмысленным.

Имя может состоять из букв, цифр, символов $ и _, не должно начинаться с цифры.

3. Функции

3.1 Именование функции

Имя функции должно быть глаголом на английском языке или начинаться с него. Для имён, состоящих из нескольких слов, используйте camelCase.

3.2 Передача функции в функцию

При передаче функции, как аргумент в другую функцию, оформляйте код как в примере ниже.

4. Отступы

4.1 Горизонтальные отступы

Отступ при вложенности — 2 пробела на каждый уровень вложенности.

4.2 Вертикальные отступы

Между логическими блоками(циклами, функциями и т.д.) следует оставлять пустую строку. Это делает код более читабельным. Избегайте блоков кода более 9 строк подряд.

5. Пробелы

• Используйте пробелы между параметрами и не используйте между именем функции и скобкой; Хорошо Плохо
• При создании анонимной функции необходимо использовать пробел перед скобкой; Хорошо Плохо
• Используйте пробелы вокруг операторов. Хорошо Плохо

6. Скобки

Открывающая фигурная скобка располагается на той же строке. Перед скобкой пробел. Закрывающая скобка располагается на новой строке.

7. Кавычки

Всегда в коде скрипта используйте одинарные кавычки, если не требуется иного. Двойные кавычки допустимы, если в этой же строке необходимо использовать апостроф (‘) или одинарные кавычки для других целей.

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

В конце выражения обязательна точка с запятой.

9. Комментарии

Для пояснения кода используются комментарии. Комментарии не исполняются интерпретатором JavaScript.

�� Comments

In computer programming, a comment is a programmer-readable explanation or annotation in the source code of a computer program.

In this article, we will learn some of known ways of writing comments, their usages, best practices and more.

Although all of the examples in this article are in JavaScript and it will be according to jsdoc format, the overall idea remains same for any programming language.

�� Table of Contents

��️ Importance

We all know that reading and understanding programs is much more difficult than writing them. And that’s why comments are always very useful when it comes to understanding another developer’s code.

And believe me, it’s not just only for other developers, it’s for future yourself, too. After looking at our own code after couple of months, even we sometimes are not sure why we wrote that piece at first place.

Jef Raskin stated importance of comments in his essay of Comments Are More Important Than Code:

The thorough use of internal documentation is one of the most-overlooked ways of improving software quality and speeding implementation.

✍️ Syntax

When it comes to syntax, there are 3 types: Single line, inline and multi-line or block level comments.

1️⃣ Single line

We write these comments with two forward slashes // :

JavaScript ignores everything immediately following the // syntax until the end of the line.

�� Inline

When we write single-line comments at end of code-line, it’s called inline comment.

These are used to annotate tiny and very specific snippets of content. Inline comments are more obvious as they are related to the exact line where we write it.

�� Multi-line or Block

Multi-line or block comments are written with opening tags /* and closing tags */ :

Although above variant is valid, but more standard practice is something like this:

• it starts with a blank line starting with /**
• each content line starts with *
• it ends with a blank line starting with */

��‍�� Usages

Unlike syntax, usages do not have pre-defined or fix set of categories. Different developers (or commentators) have provided multiple viewpoints on this. So, here I present my viewpoint:

�� Prefacing

In this, developers start each piece of code with a block comment that briefly describes it. This should summarize the purpose of its code. Preface stands as helping hand for developers (sometimes even the one who coded it), who need to understand the code in future. You can write both code and algorithmic description in this.

Take a look at below example:

��️ Metadata

Comments can often store metadata about file or a specific code. In particular, this matedata can help maintainers submit any improvements or fixes to original author, it is very crucial part if your building an open source code base.

Metadata can also be present at file level, it holds data for particular file. See below for example:

��️ Tagging

Generally, there are many keywords used for tagging, TODO: is the one most I use.

TODO: is used when you’re planning your code:

You can also use @todo tag from JSDoc.

Other tag can be one from below:

• BUG or FIXME – a known bug that should be corrected.
• HACK – a workaround.
• UNDONE – a reversal or «roll back» of previous code.

You can work with your team to introduce any new tag. For instance, if I am not happy with current approach of code, I use IMPROVE or IMPROVEMENT NEEDED tag. So that any other developer who visits that code, may think of any other and maybe better approach.

��️ Document Generation with JSDoc

JSDoc is the most widely used documentation generator for JavaScript. It generates a well-formatted, ready to publish web project.

For example, when we create a book.js file with below content:

And generate docs with help of JSDoc:

It will create a directory named out , and if you browser the files in browser they look like below:

Please checkout it’s website https://jsdoc.app/ for more details.

✅ Dos & ❎ Don’ts

Best practices for comments should be governed by company’s development guidelines. Because normative views and long-standing opinions regarding the proper use of comments in source code vary from developer to developer, some can be informal and based on personal preference, while others follow formal guidelines for a particular community.

Having said that, following are some rules I believe should be followed when writing comments.

�� Preface — Keep it short

If you’re including a preface, it shouldn’t be long. It should summarize the description of code. Trust me, no developer wants to read long essay in preface, it should be short, crisp and to the point.

�� Level of detail

Not every time it is required to write a comment. For example, take a look at below:

Now, above comment would be suitable if you’re teaching a beginner level developer. However, this would not be appropriate in the context of production code, or other situations involving experienced developers. Instead, you could write above code in below manner:

This not only saves developer from writing comments, but it also makes code self-documenting. We’re going to talk about self-documenting code in the last part.

As a side note, the best to declare such references as constants: const TODAY = new Date(); , because you don’t want to change TODAY ‘s value in rest of your code.

�� Description beyond the name

The best names for API or function are «self-documenting», meaning they tell you basically what the API does. If your comment just repeats the name, it is not providing more information.

In the ideal comment, content is beyond those words. And comment should be rewarding with some bit of information that was not immediately obvious from the API or function name.

For example, below should be avoided:

And below should be preferred:

�� Avoid short forms

Below is brief list of short forms which should be avoided and instead their full forms should be used:

Short form	Preferred full form
aka	also known as
i.e.	«that is» or «to be specific»
e.g.	for example
viz.	«in other words» or «namely»

⚓ Required Tags

@param and @return tags should be required, even if they’re redundant with the description.

�� Order of Tags

Include tags in the following order:

1. Description, @description or @desc
2. @author
3. @version
4. @param — �� Required
5. @return — �� Required
6. @exception or @throws
7. @see
8. @since
9. @deprecated

�� Swearing or Stress Relief

Sometimes, to relieve stress about development tools, competitors, employers, working conditions, or even the quality of the code itself, developers add comments in a way. The best example for this phenomenon is profanity tracker for linux kernal source code.

We should totally avoid writing such comments. But, that doesn’t mean ignore the stress, please consult with respective authority.

Other examples

I always refer to some of best open-source projects to learn the usages and best practices of comments. Angular, Lodash and Bootstrap follow really good practices. For Angular and Lodash, most of their documentation is generated from comments in code itself.

✏️ Editor Support — VS Code

As Visual Studio Code is most widely used editor for JavaScript, let’s see how it helps to write and highlight comments.

�� IntelliSense

In VS Code, you just need to type /** and it will create the closing tag. IntelliSense works for JSDoc tags.

�� Plugins

There are plenty of plugins which help developers to write better comments.

Document This is really helpful when you want to generate comments based on your function:

And these are helpers to highlight comments: Better Comments and TODO Highlight.

�� Self-documenting code

It is worth mentioning that apart from comments, there is one more approach: Self-documenting Code. This is also one way to making your code easier to understand for your peer.

Self-documenting code is ostensibly written using human-readable names, typically consisting of a phrase in a human language which reflects the symbol’s meaning, such as article.numberOfWords or TryOpen . The code must also have a clear and clean structure so that a human reader can easily understand the algorithm used. Source.

Now, it totally depends on you (and/or maybe your team/company), which one do you like to follow. I would like to highlight a few a differences between comments and self-documenting code:

Matter	Comments	Self-documenting code
⚡	Easiness	Easy	Somewhat difficult
��‍��	Expertise	None required	Some practice is required
��	Descriptiveness	Depends on who is writing it	Code is clear, but details can be sometimes missing
⏱️	Timings	Time-consuming A developer needs to write comments after a part of code, so spends more time.	Not time-consuming A developer writes coding and documenting it simultaneously. But one needs to be careful about structure.

I think self-documenting code comes with practice and a level of expertise is also required. What should be the maximum length of a variable/function name, etc. kind of rules also become necessity in self-documenting.

⛳ Conclusion

We saw and understood usage, dos and don’ts, and editor support for comments in your code. In my experience, it’s always better to use combination both, self-documenting code and comments to make your code more readable and dev-friendly.

Let me know if you follow some other best practices and if your team has a totally different approach to do so.

�� External links

This article is highly inspired from below resources:

Did you find this article valuable?

Support Dharmen Shah by becoming a sponsor. Any amount is appreciated!