Раніше я думав, що мені не потрібні коментарі, якщо я пишу самодокументований код. Однак я зрозумів, що пишу коментарі і вважаю їх дійсно корисними. Щоб побачити, скільки коментарів я пишу і які вони є, я написав скрипт для аналізу моїх коммітів 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 або більше послідовних рядків.
Висновки
Раніше я думав, що написання добре названих функцій буде означати, що коментарі не потрібні. Однак, дивлячись на те, що я насправді зробив, я помітив, що я схильний додавати коментарі в складні або неінтуїтивні частини коду. Кожен раз, коли я повертаюся до цих частин програми, я радий, що доклав зусиль, щоб додати коментар - вони були дуже корисні!