Раньше я свято верил в правило: «Чем больше комментариев — тем лучше». Мне казалось, что густо усыпанный пояснениями код свидетельствует о продуманности и заботе о будущих разработчиках. Эта иллюзия разбилась о реальность, когда я унаследовал проект с тысячами строк кода, где над каждой второй строчкой красовалось нечто вроде:
# Увеличиваем x на 1
x = x + 1
Или еще лучше:
# Возвращаем результат
return result
Я потратил больше времени на чтение и фильтрацию этого белого шума, чем на понимание самой логики. Тогда до меня и дошло: 90% комментариев не просто бесполезны — они активный мусор, который вредит читаемости и поддерживаемости кода. Сегодня мы разберем, почему это так, и научимся писать комментарии, которые действительно стоят потраченных на них символов.
Почему плохие комментарии — это мусор?
- Они создают информационный шум. Глазу приходится постоянно перескакивать с кода на бесполезный текст, чтобы убедиться, что там ничего важного нет. Это замедляет чтение и утомляет.
- Они лгут. Самая опасная разновидность — устаревшие комментарии. Программист меняет код, но забывает обновить комментарий. Следующий разработчик видит несоответствие и либо тратит время на выяснение, где правда, либо, что хуже, доверяет комментарию и допускает ошибку.
- Они поощряют плохой код. Легко написать запутанную функцию и «объяснить» ее работу в гигантском комментарии. Это путь в никуда. Вместо этого стоит приложить усилия, чтобы сама функция стала понятной.
Кладбище плохих комментариев (как НЕ надо делать)
Давайте рассмотрим типичных «вредителей» подробнее.
1. Комментарии, объясняющие очевидное (Шум)
Это самый распространенный тип мусора. Они просто переводят код с языка программирования на человеческий, не добавляя никакой ценности.
- Пример:
# Проверяем, что возраст больше 18
if age > 18:
# Если да, то разрешаем доступ
allow_access()
Что делать? Переименовать переменные и функции, чтобы код говорил сам за себя.
if user_age >= ADULT_AGE:
grant_access()
2. Устаревшие комментарии (Лжецы)
Код живет и меняется, а комментарий к нему застревает в прошлом. Такой комментарий опаснее своего отсутствия.
- Было:
# Функция всегда возвращает список целых чисел
def get_ids():
return [1, 2, 3]
Стало (после рефакторинга):
# Функция всегда возвращает список целых чисел
def get_ids():
# В случае отсутствия данных возвращаем None
return None
Решение: Если меняете код — меняйте и комментарий. А лучше пишите код так, чтобы необходимость в таких пояснениях отпала.
3. «Закомментированный» код (Археологический хлам)
Код, оставленный «на всякий случай» и закомментированный, мертв. Системы контроля версий (как Git) созданы для того, чтобы хранить историю. Такой код только захламляет файл.
- Плохо:
# old_code = calculate_old_way(data)
# new_code = calculate_new_way(data)
final_code = calculate_final_way(data)
Решение: Смело удаляйте. Если он действительно понадобится, его всегда можно найти в истории git.
4. Извиняющиеся комментарии (Комментарии-оправдания)
Они сигнализируют о проблеме, но не решают ее. Это попытка переложить ответственность.
- Пример:
# ЗДЕСЬ КОСТЫЛЬ! Извините, некогда было сделать по-человечески.
# TODO: Переписать это когда-нибудь потом.
data = json.loads(json.dumps(data)) # Костыль для глубокого копирования
Проблема: «Потом» никогда не наступает. Такой код становится вечным.
Решение: Если уж пришлось писать костыль, комментарий должен четко объяснять:
а) Почему проблема не была решена правильно (срочность, ограничения библиотеки);
б) Какие риски это несет;
в) При каких условиях это нужно переписать. Лучше всего создать задачу в трекере с этим описанием.
Оазисы смысла: какие комментарии действительно нужны?
Хороший комментарий не повторяет, что делает код, а объясняет то, что невозможно выразить самим кодом. Его главная цель — раскрыть контекст и намерение.
1. Объясняют ПОЧЕМУ (Самая ценная категория)
Код показывает как, комментарий должен объяснять почему была выбрана именно такая реализация.
- Отличный пример:
# Используем алгоритм быстрой сортировки вместо встроенной,
# т.к. встроенная нестабильна, а нам важна стабильность для бизнес-логики.
result = quick_sort(data)
Другой разработчик, увидев это, не будет тратить время на попытку заменить quick_sort на стандартную сортировку.
2. Предупреждают о неочевидных последствиях
Если функция имеет side-effect (побочный эффект), который не ясен из ее названия, это нужно явно указать.
- Пример:
# Внимание: эта функция не только вычисляет итог, но и МОДИФИЦИРУЕТ
# исходный массив `items`, очищая его.
total = calculate_and_clear(items)
3. Классифицируют сложные алгоритмы или регулярные выражения
Когда логика действительно сложна (например, математическая формула или сложное регулярное выражение), комментарий может быть спасением.
- Пример:
# Регулярное выражение для валидации email согласно спецификации RFC 5322
email_regex = r'^[a-zA-Z0-9.!#$%&’*+/=?^_`{|}~-]+@[a-zA-Z0-9-]+(?:\.[a-zA-Z0-9-]+)*$'
4. Комментарии в формате Javadoc/Docstring для API
Это, пожалуй, единственный случай, когда комментарий обязателен. Описание того, что делает функция, ее параметров и возвращаемого значения, критически важно для использования библиотек и API.
- Пример (Python):
- def calculate_commission(amount: float, currency: str) -> float:
Рассчитывает комиссию для транзакции.
Args:
amount (float): Сумма транзакции.
currency (str): Код валюты (например, 'USD', 'EUR').
Returns:
float: Размер комиссии в указанной валюте.
Raises:
ValueError: Если валюта не поддерживается.
# ... логика функции ...
Главный вывод: Код как документация
Идеальный код — это код, который не требует комментариев для понимания своей логики. Достигается это через:
- Осмысленные имена переменных и функций: user_age, is_valid, calculate_total_price().
- Выделение логических блоков в отдельные функции: Вместо комментария // Проверяем права доступа лучше создать функцию check_permissions().
- Постоянный рефакторинг: Упрощайте код, избавляйтесь от дублирования.
Правило такое: сначала попытайтесь улучшить код, чтобы комментарий стал не нужен. Если это невозможно — пишите комментарий, который объясняет не что происходит, а почему это происходит именно так.
Комментарии — это не оправдание для плохого кода, а необходимая приправа к хорошему, которая раскрывает его истинный вкус — контекст и намерение автора.
А как вы относитесь к комментариям? Сталкивались ли с особенно ужасными или, наоборот, гениальными примерами? Поделитесь опытом в комментариях!