О комментариях в коде замолвите слово

Появился пост, в комментариях к которому (какая ирония) было много мнений,
что самый лучший код — self-documenting и все такое.

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

Кто желает подискутировать — прошу к столу под кат.

В посте я кратко расскажу, как использую комментарии в своей разработке уже 10 лет и плавно затрону тему документации вообще.

Комментарии помогают найти забытый код

Есть у Артемия Лебедева (мастер эпатажа ИМХО) такое правило — он знает образ своего мышления. И если забыл что-то, например, где нужная фотка лежит, то знание системы категоризации своей позволяет найти быстро нужную фотку.

То же самое и с комментариями. У меня есть проекты, которые не трогал много лет. Открываешь в IDE этот проект, вбиваешь пару слов, и находишь нужные файлы и классы без усилий. То бишь первая тема — писать, что делает хотя бы каждый файл, в самом начале. Очень экономит время поиска. А когда есть еще и тесты — поиск упрощается совсем.

Комментарии помогают разрабатывать в IDE

Так устроены IDE, что они держат всякие javadoc в памяти. И когда ты пишешь новый код, всплывающие подсказки очень облегчают жизнь, поясняя, что и как. Особенно когда работает над проектом команда, и ты используешь сторонние методы.

Комментарии помогают в создании документации

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

Документация вообще

Мне, спустя года, стало нравится высказывание «лень — двигатель прогресса». Считаю, левый программист, админ — это врожденное и полезное качество.

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

Когда мне дали несколько нагруженных проектов, где вопросы разработчиков были очень частыми, я стал применять принцип трех гвоздей. На каждый типовой вопрос после третьего обращения я писал FAQ, на каждую задачу — туториал с комментариями в коде туторила.

Через полгода на 80% я отвечал ссылками на туториалы и FAQ и не выходил из потока, хотя количество моих подчиненных выросло на проектах от двух до пяти.

Вывод

Если вы работаете один, если у вас масса времени, если вы не делаете проекты в промышленном масштабе — то можно писать красивый самодокументирующийся код. Я так делал в своих поделках до поры до времени.

Если же вы работает в команде, у вас есть проекты, которые вырастут до >100,000 строк кода, и вы будете возвращаться к ним через пару лет — комментарии вам просто необходимы. Хотя бы на уровне, что делает тот или иной файл, тот или иной большой важный кусок логики.

А если еще при этом вы является Senior, Team Lead разработчиком, и в ваши обязанности входит еще и работа с нетехническими людьми, либо работа с новичками — то документация, наращиваемая по эволюционному принципу on-demand для повышения, так сказать, cache hit %, станет существенной экономией вашего времени.