Комментарии - такая неоднозначная тема в коде. Это обсуждение почти так же плохо, как пробелы против табуляции. Есть один большой лагерь, который утверждает, что код должен быть ясным и легким для понимания без комментариев. Другой лагерь - комментарии, которые помогают читателю понять функциональность кода. Лично я считаю, что сочетание того и другого работает лучше всего, потому что аннотации помогают читателю понять код. В какой бы лагерь вы ни попали, есть определенные типы комментариев, которые следует удалить из кода.
Пароли или ключи
Хранить пароли и ключи внутри кода - это плохая практика, также плохая практика - размещать их в комментариях.
# Для запуска в режиме отладки пользователь bugslayer и передает BugSpray $ 2
TODO комментарии
Эти комментарии к задачам удобны во время разработки кода в ветке разработки, но они должны быть преобразованы в систему отслеживания задач при слиянии с основным репозиторием.
Комментарии к личному сообщению
Эти комментарии никому не помогают и были добавлены в код по личным причинам. В зависимости от того, что это за сообщение, может быть лучше иметь их в проектном документе или в файле README репозитория. Вот несколько примеров:
# Боб написал эту библиотеку в 2017 году во время нашего хакатона
# Project: Warp Speed Команда: Barracuda Год: 1978
# Прими синюю таблетку и присоединяйся к нам
# Мы потратили 3 недели на написание этого кода. Это нужно переписать
Первые два примера полезны как в README, так и в проектном документе, но два последних комментария бесполезны.
Слишком много и / или ненужных комментариев
Иногда более новые разработчики перебарщивают с комментариями, добавляя комментарии для каждой строки или потока управления. Эти комментарии не нужны, если код использует четкое именование переменных и функций.
# рассчитать и создать отчет
# рассчитать годовой объем продаж
годовой = квартал 1 + квартал 2 + квартал 3 + квартал 4
# сохранить в базе
db.save (отчет)
# создать отчет о продажах
report = CreateSalesReport (годовой, первый квартал, второй квартал, третий квартал, четвертый квартал)
# отчет по электронной почте
server.Email (отчет)
Закомментированный код
На самом деле это не комментарии, это код, который был закомментирован. Примерами являются код отладки, мертвый / нерабочий код или проблемный код. Во-первых, что такое отладочный код? Это код, написанный для помощи в отладке программы, такой как операторы печати, которые выводят переменные или отслеживают потоки управления. Вместо закомментированного отладочного кода лучше поместить операторы печати, которые распечатываются только в режиме отладки, или помещать распечатки в модульные тесты в качестве тестовых примеров assert, чтобы убедиться, что результат соответствует ожидаемому.
Мертвый код - это то, что не работает или в нем нет необходимости. Он был закомментирован, но не был удален из программы, потому что, возможно, однажды он будет полезен. Однако любой современный репозиторий кода будет хранить историю, поэтому нет необходимости больше хранить эти типы кода.
Наконец, есть проблемный код - это код, который может работать или может выйти из строя. Это ошибочный код, который нужно исправить. Этот тип кода похож на мертвый код, но он был закомментирован, потому что он слишком опасен для использования в продукте до того, как он будет исправлен. Суть в том, чтобы либо исправить код, либо удалить закомментированный код. Его всегда можно вернуть обратно в продукт через историю репозитория кода.
Чистый код
Удаление ненужных комментариев упростит понимание и чтение, так как он станет понятнее и понятнее. Есть и другие вещи, которые можно сделать для улучшения практики кодирования, например, четкое именование переменных и функций. Об этом мы поговорим в другой раз.
