Не комментируйте свой код — перепишите его

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

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

Так что же нужно комментировать?

Вообще, я не сказал, что комментарии не нужны совсем, в программировании довольно редко используются какие-либо абсолютные соглашения. Вы должны быть уверены, что есть на самом деле весомая причина использования пояснений в коде. Я использую их как предупреждающие знаки о том, что программисту стоит обратить особое внимание на этот участок. Скорее всего, он чем-то опасен или делает какую-то неочевидную вещь. Можно ли сказать то же самое про любой кусок кода, который чем-то сложен и сильно запутан? Да, можно! По этой причине я часто использую комментарии в legacy-коде, над которым не ведётся активная работа. Т.к. из-за внешних бизнес-условий мы не всегда можем проводить рефакторинг так часто, как хотелось бы, да и иногда лучше просто не трогать то, что и так работает, то комментарии могут быть полезны. Я считаю, что в данном случае это необходимое зло.

Почему же комментарии — это зло?

Короткий ответ в том, что они часто врут нам. Они говорят, что делает данный код и часто могут не изменяться в последующих ревизиях. Например, есть функция, которая возвращает string, и я так и написал в комментариях. Но затем потребовалось изменить её, и какой-то другой программист внёс быстрые правки, поменяв тип возвращаемого значения на int, но забыл обновить комментарии. Это довольно распространённый случай. Вот мы и пришли к ситуации, когда комментарии говорят одно, а происходит на самом деле совсем другое.

Мы знаем, что правда всегда на стороне кода. Ведь это именно то, что будет происходить в реальном продукте. Так зачем же читать комментарии, которые потенциально могут быть ошибочны и тратить время на них, когда можно просто посмотреть на код и понять, что он делает?

Код никогда не лжёт, комментарии иногда делают это. — Ron Jeffries

Как писать код так, чтобы комментарии были не нужны?

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

			class Dog
  def bark
      puts "woof"
  end
end
		

Отрывок выше является хорошим примером выразительного кода. Даже ребёнок сможет понять, что это собака, и она может лаять. Конечно, в большинстве случаев реальный код намного сложнее и далеко не так очевидно, как написать его правильно, но общие принципы везде одинаковые. Старайтесь давать имена сущностям так, как будто вам надо будет объяснить это ребёнку. В данном примере мы можем описать код как «собака умеет лаять». Точно так же можно сказать «пользователь может залогиниться» или «пользователь может изменить данные своего профиля».

Пишите код так, как будто сопровождать его будет склонный к насилию психопат, который знает, где вы живёте. — Martin Golding

Эта цитата всегда казалась мне забавной, пока я сам не столкнулся с сопровождением кода, написанного просто ужасно. Мне на самом деле хотелось как следует врезать его автору за то, что он сделал код настолько сложным для сопровождения. Простые изменения, которые заняли бы минут 20 в коде с хорошей архитектурой, растянулись на 4 часа.

Внимательно относитесь к именам переменных, функций и классов

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

Любой дурак может написать код, понятный компьютеру. Хорошие программисты пишут код, понятный людям. — Martin Fowler

В этой цитате Мартин Фаулер описал всю суть того, почему нужно избегать комментариев. Ваш код должен быть настолько хорошо читаемым, что любой другой программист смог бы разобраться в нём. А комментарии просто кричат о том, что вы не сможете понять эту строчку без дополнительных пояснений. Вот почему я избегаю их, и вам советую поступать так же.

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

Перевод статьи «Don’t Comment Your Code – Rewrite It»