Комментировать или не комментировать? Точка зрения junior’a

Этот пост будет совсем коротким. В общем-то, одного заголовка достаточно для того, чтобы догадаться, о чём я хочу сказать.

В последнее время я постоянно вижу споры на эту тему. И мне кажется весьма странным, что, на мой взгляд, бОльшая часть склонна писать «самодокументирующийся» код. Многие люди требуют удаления комментариев, которые кажутся им очевидными.
Но есть 2 больших категории людей, которым отсутствие комментариев очень мешает. Это люди, не имеющие опыта в программировании, а также те, кто недавно вступил в команду, работающую над большим проектом (особенно в том случае, если он уже начал расползаться под собственным весом).

Если это кажется вам банальным, просто прокрутите страницу дальше 🙂

Итак, чуть подробнее.

Думаю, ни для кого не секрет, что многие компании принимают к себе начинающих программистов. Они обычно много не просят (во всяком случае, после пары проваленных собеседований), а нудной мелкой работы хватает у всех.
Что видит юниор, глядя в незнакомый код? Видит он кучу, скажем, sql запросов, местами прерываемых примерно таким кодом:

com.bzpn.vpp.system.cup.FGCFTemplateImplication.removeEntity(broken);

Что он делает дальше? Правильно, десяток минут хлопает глазами, а затем просит разъяснений у более опытного сотрудника, впустую растрачивая его время.
На мой взгляд, такой ситуации не возникло бы, если бы код содержал комментарии, поясняющие, что делает конкретный блок.
Я понимаю, что опытным программистам, на которых всё держится, такие комментарии не нужны, а многие даже считают их раздражающими и приравнивают лишние комментарии в коде к волосам в супе (привет, Дмитрий 😉 ). Но разве так сложно поддерживать в актуальном состоянии один лаконичный комментарий на 30-50 строк кода?

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

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