Раньше я думал, что мне не нужны комментарии, если я пишу самодокументированный код. Однако я понял, что пишу комментарии и считаю их действительно полезными. Чтобы увидеть, сколько комментариев я пишу и какие они есть, я написал скрипт для анализа моих коммитов git за последние шесть лет. В общей сложности семь процентов моих утвержденных строк содержали комментарии. В этом посте есть подробности о том, что считать хорошими и плохими комментариями, а также дополнительная статистика из моего скрипта.
Javadoc — самый бесполезный
Одна из причин, по которой я скептически относился к комментариям, заключалась в преобладании комментариев в стиле Javadoc. Этот стиль комментирования существует и на других языках. Вот пример на Python, который я только что придумал, но который является представителем этого стиля:
Проблема большинства этих комментариев в том, что они несут очень мало информации. Часто это просто повторение имени метода и имен параметров в нескольких словах. Эти комментарии могут быть полезны для API, открытых извне, но в приложении, где у вас есть доступ ко всему исходному коду, они в основном бесполезны. Если вам интересно, что делает метод или каков допустимый диапазон ввода для параметра, вам лучше просто прочитать код, чтобы увидеть, что он делает. Эти типы комментариев занимают много места, но не представляют особой ценности.