Не делай так: повесть в комментариях

Огромная, как по мне, задача при написании чистого кода — это правильная работа с комментариями. Поскольку тема обширная, коснёмся лишь одного конкретного вопроса: размер имеет значение?

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

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

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

Но проблемы не только с большими комментариями! На другой стороне нашего глобуса безумия — рассказы про код, который сам себя документирует.

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

Хороший комментарий — это не извинение за плохой код. Это помощь тому, кто придёт после вас. Иногда этим человеком будете вы сами через какое-то время. Но не забывайте, что вы сущность в коде описываете, а не дуб.

Поэтому #неДелайТак - пиши комментарии осмысленно!

P. S. А вообще тема большая, и явно не для формата коротенького поста. Рано или поздно придумаю, как бы рассказать всё про комментарии :)

🎤feelin #cleanCode