Pull to refresh

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

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

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


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

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


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

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

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


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

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


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

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


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

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

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

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

Вывод


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

Можно писать хороший читаемый код, но для восприятия проекта в целом и решения практических задач, изложенных выше, комментарии полезны.

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

Ну и конечно, не забываем про эффект Даннига-Крюгера. Человек можете считать свой код читаемым и понятным, но не факт, что это так для окружающих.

Особенно актуально после принятия проектов от нубов, которые прочитали Макконнелла про самодокументирующийся код и запомнили, что комментарии писать не надо, а все остальные рекомендации к оформлению кода и code conventions проигнорировали напрочь — или, не дай Бог, фриланс-заказ из прошлого по поддержке индусского сайта).

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

Ссылки в тему
1.There is No Such Thing as Self-Documenting Code – It’s a Myth

2. Bloated names, and the myth of self-documenting code

3. Intent versus action, or the myth of self-documenting code

4. Self Documenting Code and other Myths
Tags:
Hubs:
+17
Comments 23
Comments Comments 23

Articles