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

Комментарий — пояснительная записка в исходном коде программы, предназначенная для людей и игнорируемая компилятором или интерпретатором. Комментарии не влияют на результат выполнения программы, но существенно повышают читаемость и сопровождаемость кода. В большинстве языков программирования они оформляются специальными символами-маркерами, а их содержимое исключается из исполняемого файла на этапе компиляции или трансляции.

¶Назначение

Комментарии выполняют несколько функций:

• Пояснение логики — объяснение сложных алгоритмов, неочевидных решений и математических формул.
• Документирование — описание назначения функций, классов, модулей и их параметров (в частности, через системы генерации документации: Javadoc, Doxygen, Sphinx, JSDoc).
• Отладка — временная блокировка фрагментов кода без его удаления.
• Маркировка — отметки TODO, FIXME, HACK, которые указывают на незавершённые или проблемные участки.
• Лицензирование — указание авторских прав и условий использования файла.

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

Способ оформления комментариев зависит от языка программирования. Существуют три основных вида:

Типичные маркеры:

• // — однострочный комментарий в C-подобных языках;
• / ... / — многострочный комментарий в C-подобных языках;
• # — однострочный комментарий в Python, Ruby, Shell, YAML;
• -- — однострочный комментарий в SQL, Lua, Haskell;
• REM — однострочный комментарий в BASIC и batch-файлах;
• <!-- ... --> — комментарий в HTML и XML;
• % — комментарий в LaTeX и MATLAB.

В Python, в отличие от C-подобных языков, многострочных комментариев как синтаксической конструкции нет; вместо них используется строка-документация (docstring), которая формально является строковым литералом, но традиционно используется для документирования.

¶Правила хорошего стиля

Практика программирования выработала ряд рекомендаций по написанию комментариев:

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

¶Комментарии и документация

Комментарии — часть процесса документирования программного обеспечения. Специализированные генераторы документации (Javadoc, Doxygen, Sphinx, rustdoc) извлекают структурированные комментарии и превращают их в HTML- или PDF-документацию. Такой подход позволяет поддерживать документацию в синхронизации с кодом, поскольку она хранится рядом с ним.

¶Критика

У части разработчиков существует практика «код без комментариев», основанная на убеждении, что хорошо структурированный и самодокументирующийся код не требует пояснений. Критики этой позиции указывают, что даже идеально читаемый код не передаёт контекст: историю решений, ограничения внешних API, особенности бизнес-логики. Компромиссным подходом считается баланс: комментарии там, где код сам по себе недостаточно выразителен.

¶Пример

```python def fibonacci(n):

¶Возвращает n-е число Фибоначчи итеративно — O(n) по времени, O(1) по памяти

a, b = 0, 1 for _ in range(n): a, b = b, a + b return a ```

В этом примере комментарий объясняет назначение функции и её асимптотическую сложность — сведения, которые не выводятся непосредственно из тела функции.

Источники:

• «The Pragmatic Programmer» Дэвида Томаса и Эндрю Ханта
• «Clean Code» Роберта Мартина
• «Code Complete» Стива Макконнелла
• Документация Python (PEP 257 — Docstring Conventions)
• Документация Doxygen и Javadoc