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

Javadoc — самый бесполезный

Одна из причин, по которой я скептически относился к комментариям, заключалась в преобладании комментариев в стиле Javadoc. Этот стиль комментирования существует и на других языках. Вот пример на Python, который я только что придумал, но который является представителем этого стиля:



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

Самодокументируемый код

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

Когда комментировать

Написание самодокументирующегося кода поможет вам в долгосрочной перспективе. Однако бывают случаи, когда полезно иметь больше информации. Например, комментарий об использовании зон набора в коде ниже:



Еще один пример:



Часто можно услышать совет «пишие комменте ПОЧЕМУ, а не ЧТО». Хотя это, вероятно, охватывает большинство моих комментариев, это не то, как я думаю о том, когда комментировать. Вместо этого я обычно пишу комментарий, когда есть что-то особенно сложное, либо в домене, либо в том, как выполняется реализация.

Стандартный совет от толпы исповедующих принцип: “никаких комментариев не требуется” (к которой я когда-то принадлежал) — переписать код, чтобы вам не нужно было его комментировать. Однако это не всегда возможно. Иногда домен просто слишком сложен. Иногда усилия по переписыванию кода были бы слишком большими по сравнению с добавлением комментария.

Еще одна жалоба на комментарии заключается в том, что они будут не синхронизированы с кодом, тем самым препятствуя вашему пониманию кода, а не помогая ему. Хотя это иногда случается, для меня это не было большой проблемой. Почти во всех случаях, которые я анализировал, комментарии все еще оставались в силе. Они также были очень полезны. Каждый раз, когда я натыкался на один из таких комментариев, я был счастлив, что написал его. Это не займет много времени, чтобы забыть некоторые детали и нюансы проблемы, которую вы решаете, и наличие комментария с некоторым дополнительным контекстом и объяснением было здорово.

Логи как комментарии

Иногда вы получаете комментарий “на халяву”, если регистрируете пояснительное сообщение. В приведенном ниже примере инструкция log объясняет, что произошло, поэтому нет необходимости в комментариях.

Анализ комментариев

Когда я впервые подумал о том, чтобы проверить, сколько комментариев содержится во всех моих коммитах, я подумал, что будет достаточно одной строки, чтобы найти комментарии во всех моих коммитах Python (я комментирую только с помощью #):

git log --author=Henrik -p|grep '^+[^+]'|grep '#' | wc -l

Однако вскоре я понял, что мне нужны более подробные сведения. Я хотел провести различие между комментариями в конце строки и комментариями всей строки. Я также хотел узнать, сколько “блоков комментариев” (последовательных строк комментариев) у меня было. Я также решил исключить тестовые файлы из анализа. Кроме того, я хочу обязательно исключить любой закомментированный код, который там оказался (к сожалению, таких случаев было несколько). В конце концов я написал скрипт на python для анализа. Входными данными для скрипта были выходные данные git log --author=Henrik -p.

Из выходных данных я увидел, что 1299 из 17817 добавленных строк моих содержали комментарии. Был 161 комментарий в конце строки и 464 однострочных комментария. Самый длинный блок комментариев составлял 11 строк, и было 96 случаев блоков комментариев, которые имели 3 или более последовательных строк.

Выводы

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