В мире программирования использование комментариев уже давно является предметом долгих споров. Хотя некоторые разработчики выступают за развернутое комментирование для улучшения читаемости кода, комментарии часто могут принести больше вреда, чем пользы. Они иногда дают читающему неверное представление о реальной работе кода, заставляя полагаться на слова автора, а не на саму логику программы.
В чем проблема комментирования?
Комментарии могут устаревать, вводить в заблуждение или даже содержать ложную информацию. С течением времени и по мере развития кода то, что когда-то было верным утверждением в комментарии, может перестать отражать реальность. Это несоответствие приводит к путанице, заставляя разработчиков в будущем интерпретировать код через призму потенциально вводящего в заблуждение комментария. Вместо того чтобы прояснить код, комментарий может скрыть его истинное назначение.
Когда стоит использовать комментарии?
Несмотря на аргументы против комментариев, иногда они все же не мешают, а помогают лучше понять код. Вот пять сценариев, в которых комментарии могут быть оправданы.
- Информативные комментарии. В идеале код должен быть понятен сам по себе, однако в некоторых случаях комментарий может дать ценный контекст. Например, объяснение возвращаемого значения функции помогает лучше понять процесс, особенно в сложных случаях. Тем не менее старайтесь, чтобы имена функций и переменных были достаточно описательными, чтобы свести к минимуму необходимость в таких комментариях.
- TODO-комментарии. Эти комментарии указывают на незавершенные задачи или области, требующие доработки. Они служат напоминанием о необходимости пересмотреть и доработать определенные участки кода. Есть низкая вероятность того, что TODO-комментарии будут проигнорированы, поскольку они обычно связаны с текущей работой, требующей внимания.
- Предупреждения о последствиях. Некоторые сегменты кода могут быть связаны с такими рисками, как, например, проблемы с производительностью или потенциальные ошибки. Комментарии, предупреждающие разработчиков о таких подводных камнях, оказываются спасительным кругом в таких ситуациях. Например, комментарий типа
# CONSUMES A LOT OF COMPUTING RESOURCES(«потребляет много вычислительных ресурсов») сообщает специалистам по сопровождению кода о последствиях использования определенной функции.
- Разъяснение сложных алгоритмов. Некоторые алгоритмы или логика слишком запутанны, чтобы их можно было сразу понять, даже при наличии корректно названных переменных и функций. Краткий комментарий, объясняющий цель или ключевые шаги алгоритма, экономит время специалистов, которые будут читать и анализировать код (и ваше время тоже). Например, комментарий типа
# Uses binary search to find the insertion point(«использует двоичный поиск для поиска точки вставки») может понадобиться, если речь идет о сложной структуре данных или алгоритме.
- Комментарии по юридическим вопросам/соответствию. В некоторых случаях ваш код должен соответствовать определенным юридическим требованиям, стандартам соответствия или нормативным предписаниям. Комментарии могут описать эти требования, указывая на ограничения или требования, которым соответствует код. Например,
# This section handles GDPR compliance for user data.(«в этом разделе рассматривается соответствие регламенту GDPR в отношении пользовательских данных»).
Когда комментарии вредят?
Не все комментарии одинаково полезны. Ниже перечислены случаи, когда комментариев следует избегать.
- Комментарии, вносящие шум. Эти комментарии утверждают очевидное и добавляют ненужную многословность. Например, комментарий типа
# adds to animal list(«добавляет в список animals») перед строкойanimal.append(dog)является лишним. Такие комментарии тратят время читателей и загромождают код.
- Нелокальная информация. Комментарии должны относиться только к конкретной функции или строке, на которую они ссылаются. Предоставление глобального контекста в локальном комментарии запутывает разработчиков, которые пытаются понять непосредственную логику кода.
- Неочевидные комментарии. Некоторые комментарии могут показаться понятными, но не найти отклика у других специалистов. Убедитесь, что ваши комментарии напрямую связаны с кодом, который они описывают. Избегайте необходимости дополнительных объяснений.
- Короткие функции. Если функция лаконична и ее назначение можно понять из названия, комментарии часто не нужны. Короткие понятные функции не нуждаются в пояснениях.
Подведем итоги
Комментарии должны быть крайним средством, а не устоявшейся привычкой. Использование комментариев часто свидетельствует о неспособности программиста передать смысл программы через сам код. Вместо того чтобы вводить читателей в заблуждение неактуальной информацией, стремитесь к ясности и выразительности в именах классов, функций и переменных.
В заключение хотелось бы сказать следующее: несмотря на исключительные ситуации, когда комментарии могут быть полезны, общее правило остается неизменным — избегайте комментариев любой ценой. Возьмите на себя труд писать четкий, понятный код, который говорит сам за себя.
Читайте также:
- Руководство разработчика по оптимизации скорости работы веб-сайтов
- Почему все веб-сайты выглядят одинаково?
- Как оптимизировать пулл-реквесты и порадовать тех, кто проверяет ваш код
Читайте нас в Telegram, VK и Дзен
Перевод статьи Rohan Raghuwanshi: The Case Against Code Comments: Why Less is More
