Комментарии в программировании¶

Комментарии — это пояснения, вставляемые в исходный код программ, которые интерпретатор или компилятор не исполняет. Они предназначены для людей, читающих код: разработчиков, ревьюеров, новичков в проекте. Комментарии сопровождают программы практически во всех языках программирования — от C и Python до JavaScript и Rust.

¶Назначение

Основные функции комментариев:

• Пояснение — объяснение сложных алгоритмов, неочевидных решений, математических формул.
• Документирование — описание назначения функций, классов, параметров и возвращаемых значений.
• Отладка — временная блокировка фрагментов кода без его удаления.
• Метки — обозначение разделов исходного файла, авторства, лицензии, ссылок на задачи.

¶Синтаксис в разных языках

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

Однострочный комментарий начинается с маркера и продолжается до конца строки. В Python и Ruby:

```python

¶вычисляем сумму элементов

total = sum(values) ```

В C-подобных языках:

``c // инициализируем счётчик int count = 0; ``

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

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

```c /*

• Функция вычисляет факториал числа n.
• Предполагается, что n >= 0.

*/ long factorial(int n) { ... } ```

В Python многострочных комментариев как таковых нет — вместо них используются строковые литералы (docstrings), которые интерпретатор сохраняет в атрибут __doc__ объекта.

¶Документирующие комментарии

Многие языки поддерживают особый формат документации, из которого автоматически генерируются справочные материалы. Типичные системы:

• Javadoc (Java) — комментарии с тегами @param, @return, @throws.
• Doxygen (C, C++, Python и др.) — поддерживает @brief, @param, @return.
• docstring (Python) — строка-литерал в начале функции или модуля.
• JSDoc (JavaScript) — комментарии вида /** ... */ с тегами @param, @returns.

Пример JSDoc:

```javascript /**

• Складывает два числа.
• @param {number} a — первое слагаемое
• @param {number} b — второе слагаемое
• @returns {number} сумма

*/ function add(a, b) { return a + b; } ```

¶Правила написания комментариев

1. Комментарий должен объяснять «почему», а не «что». Код сам показывает, что делает программа; комментарий добавляет контекст, которого в коде нет.
2. Не комментировать очевидное. Строка i = i + 1; // увеличиваем i на 1 не несёт информации.
3. Обновлять комментарии при изменении кода. Устаревший комментарий опаснее его отсутствия.
4. Использовать полные предложения с заглавной буквы и точкой в конце — по аналогии с обычным текстом.
5. Избегать «мёртвого кода» — закомментированных фрагментов, которые давно не используются. Такой код удаляют, а не хранят в комментариях.
6. Не дублировать информацию, которая уже есть в названиях переменных и функций.
7. Писать на языке проекта. Если весь код и документация на английском, комментарии тоже пишут на английском.

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

Временное комментирование кода — распространённый приём при отладке:

```python

¶print(debug_info) # временно отключено

```

Злоупотребление этим приёмом приводит к накоплению закомментированного кода в репозитории. Системы контроля версий (Git) делают такое хранение избыточным: любой фрагмент можно восстановить из истории коммитов.

¶Комментарии и линтеры

Статические анализаторы (линтеры) вроде ESLint, Pylint, RuboCop проверяют не только код, но и комментарии: отсутствие документации у публичных API, устаревшие пометки TODO, FIXME, HACK, нарушения стиля. Некоторые инструменты умеют автоматически удалять закомментированный код и предупреждать о дублировании комментариев.

¶Историческая справка

Первые языки программирования — Fortran (1957) и COBOL (1959) — уже поддерживали комментарии, поскольку программы писались на перфокартах и требовали пояснений для операторов ЭВМ. В языке C комментарии вида / ... / появились в 1972 году, а однострочные // были добавлены в стандарт C99 (1999) по образцу C++. В Python синтаксис # унаследован от языка ABC и Bash.