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

в 21:16, , рубрики: junior, комментарии, невидимый тег, Программирование, холивар, метки: , , ,

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

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

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

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

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

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

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

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

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

upd. Судя по минусам, меня как-то не так поняли. На всякий случай, кратко о том, что я хотел донести: решая, нужно ли комментировать код, принимайте во внимание то, что неопытный программист, который получит его в будущем, может потратить на расспросы гораздо больше своего и вашего времени, чем уйдёт у вас на краткое комментирование.

Автор: IDOL1234

Источник

* - обязательные к заполнению поля


https://ajax.googleapis.com/ajax/libs/jquery/3.4.1/jquery.min.js