Добавлять комментарии к своему коду или нет? И да, и нет. Или так: «Сначала вы должны стремиться сделать свой код настолько простым, насколько это возможно для понимания, не полагаясь на комментарии как на основу. Только в тот момент, когда код не может быть упрощен для понимания, вам стоит начать добавлять комментарии». Джефф Этвуд написал это еще в 2006 году, но сегодня это так же актуально, как и тогда, если не больше.

Аргументы против комментариев

Если вы поднимете эту тему, очень скоро кто-то обязательно скажет вам, почему вы не должны загромождать свой код комментариями. Одна из основных жалоб на комментарии заключается в том, что они мешают восприятию кода. «Хороший код самодокументируется», - говорится в поговорке, а добавление комментариев иногда может маскировать плохой код, но не в лучшую сторону. Как писал Беннет Гарнер:

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

Это достаточно плохо, но проблема усугубляется с возрастом комментариев. Как утверждал Марко Брешиани: «Не верьте комментариям: они никогда не обновляются. Только код говорит правду». Комментарии могут быть полезны в некоторый момент, но по мере изменения кода (что происходит часто), комментарии часто этого не делают. Это оставляет код загроможденным устаревшими комментариями, которые могут привести к путанице, а не к разъяснениям. «В идеале разработчики должны обновлять свои комментарии при обновлении кода, но этого не происходит.

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

Аргументы за комментарии

Старайтесь изо всех сил, чтобы ваш код был «самодокументируемым», чего не может сделать сам код, - так это объяснить причину написания себя в этом виде. Как отметил Джеф Раскин: «Основной причиной того, что код никогда не может быть самодокументируемым, и генераторы автоматической документации не могут создать то, что необходимо, - это то, что они не могут объяснить, почему пишется программа, и обоснование выбора того или иного метода. Они не могут обсуждать причины, по которым были приняты определенные альтернативные подходы ". Например, вам может потребоваться объяснить, почему был выбран неинтуитивный путь, как сделал Билл Суурр, и тем самым избавил будущих разработчиков от необходимости использования более очевидного (но неправильного) подхода.

Опять же, основной акцент должен быть на написании качественного, краткого кода, который (более или менее) объясняет сам себя. Там, где это невозможно (и это не всегда возможно), «думайте о комментариях как об обледенении на торте, которые существуют, чтобы предоставить читателю информацию, которая не может быть легко выражена самим кодом», говорит Брайан Ханнауэй.

«Важно помнить свою аудиторию», - продолжает он. Неправильно полагать, что те, кто позже столкнется с вашим кодом, будут иметь такой же уровень знаний. Таким образом, он предложил, обслуживать менее опытных специалистов:

«Вы должны сделать ваши комментарии доступными и полезными для максимально широкого круга читателей. Если вы опытный технический лидер с хорошими знаниями предметной области, вам не следует комментировать свой код, предполагая, что [человек], который будет далее читать ваш код, будет знать столько же, сколько и вы. Вместо этого пишите свои комментарии для менее опытных разработчиков».

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

No Comments