Этот пост будет совсем коротким. В общем-то, одного заголовка достаточно для того, чтобы догадаться, о чём я хочу сказать.
В последнее время я постоянно вижу споры на эту тему. И мне кажется весьма странным, что, на мой взгляд, бОльшая часть склонна писать «самодокументирующийся» код. Многие люди требуют удаления комментариев, поясняющих то, что кажется им очевидными.
Но есть 2 больших категории людей, которым отсутствие комментариев очень мешает. Это люди, не имеющие опыта в программировании, а также те, кто недавно вступил в команду, работающую над большим проектом (особенно в том случае, если он уже начал расползаться под собственным весом).
Если это кажется вам банальным, просто прокрутите страницу дальше :)
Итак, чуть подробнее.
Думаю, ни для кого не секрет, что многие компании принимают к себе начинающих программистов. Они обычно много не просят (во всяком случае, после пары проваленных собеседований), а нудной мелкой работы хватает у всех.
Что видит юниор, глядя в незнакомый код? Видит он кучу, скажем, sql запросов, местами прерываемых примерно таким кодом:
com.bzpn.vpp.system.cup.FGCFTemplateImplication.removeEntity(broken);
Что он делает дальше? Правильно, десяток минут хлопает глазами, а затем просит разъяснений у более опытного сотрудника, впустую растрачивая его время.
На мой взгляд, такой ситуации не возникло бы, если бы код содержал комментарии, поясняющие, что делает конкретный блок.
Я понимаю, что опытным программистам, на которых всё держится, такие комментарии не нужны, а многие даже считают их раздражающими и приравнивают лишние комментарии в коде к волосам в супе (привет, Григорий ;) ). Но разве так сложно поддерживать в актуальном состоянии один лаконичный комментарий на 30-50 строк кода?
Я не утверждаю, что комментировать надо всё. Кроме того, я не прошу расставлять пояснения в редактируемых исходных кодах. Часто это замедляет процесс разработки. Но, на мой взгляд, их наличие существенно упрощает понимание логики программы без углубления в детали реализации. И да, я знаю про javadoc :)
Комментарии подобны выступающим из склонов крутого холма камням. Они раздражают уверенно идущих по верху, но часто оказывают неоценимую помощь тем, кто только начинает восхождение…
upd. Судя по минусам, меня как-то не так поняли. На всякий случай, кратко о том, что я хотел донести: решая, нужно ли комментировать код, принимайте во внимание то, что неопытный программист, который получит его в будущем, может потратить на расспросы гораздо больше своего и вашего времени, чем уйдёт у вас на краткое комментирование.
Автор: IDOL1234
