В последнее время, набирает популярность мысль, что комментарии в коде — дело не обязательное, и даже вредное. Буквально вчера вечером, общаясь со знакомым молодым программистом, попросившим посмотреть его код, я обнаружил, что комменты отсутствовали вовсе, даже привычные описания методов. На мой удивленный смайлик, был ответ: “Комментарии — первый признак плохого кода”. И черт бы с ним, с начинающим программистом, но я периодически читаю что-то похожее в блогах, и слышу от коллег. Может программирование в очередной раз сделало шаг вперед, а я, среди отстающих? Под катом, немного размышлений, о том, когда и почему стоит или не стоит комментировать свой код.
Итак, есть два основных утверждения против комментов в коде:
Утверждение 1: “Код — сам себе лучшая документация”.
Или более радикальное “Комментарии — первый признак плохого кода”.
В принципе, мысль верная, код должен быть чистым. А чистый код в комментариях не нуждается, он и так понятен. Если у вас возникло желание, объяснить посредством комментария, что означает данная переменная — может лучше переименовать ее так, что бы это стало понятно из названия? Если вам кажется что алгоритм метода немного запутан, может вместо того, что бы писать комментарий, стоит переписать алгоритм, сделав его более понятным и логичным?
К сожалению, в реальной жизни, не всегда получается выдавать красивый и логичный код. Иногда не хватает времени на качественный рефакторинг, и просто пишешь как можешь. Иногда сама бизнес-логика настолько запутана, что без 100 грамм ее не реализуешь. А когда реализуешь, хочется забыть об этой задачи и, на всякий случай, принять душ, раз пять. А иногда, то, что вам кажется красивым и логичным, может вызвать затруднения у ваших коллег.
Так может ли код быть самому себе лучшей документацией? Конечно может, но для уверенности, не бойтесь вставить лишнюю строчку комментария, или хотя бы сделать отсылку на используемый паттерн. Возможно, в будущем, это сэкономит кому-то немного времени.
Утверждение 2: “Комментарии могут устареть”.
Имеется в виду, что комментарии, могут в какой-то момент перестать соответствовать коду. Например, вы написали некий метод, в теле которого оставили немало комментариев, ибо, согласно предыдущему абзацу, хотите сэкономить время своим коллегам. Через пол года ваш коллега, изменил метод, но впопыхах, или по неосмотрительности, забыл поправить комментарии. А еще через пол года, ваш другой коллега, потерял немало времени, ибо был введен в заблуждение неактуальными комментариями.
Проблема не надуманна, я, например, не раз встречал комменты, которые не соответствуют коду… да чего там… я и сам, бывало, забывал переписывать комментарии. Проблема есть, но не думаю, что исключить комментарии вообще — лучшее решение. Просто надо быть внимательным, и не забывать исправлять комментарии при исправлении кода.
Почему?
Поймите меня правильно, я не агитирую за комментирование каждой строчки. Более того, я и сам считаю комментарии в стиле:
$i++; // Увеличиваем счетчик
признаком плохого кода. Комментарии не должны дублировать код! Они должны дополнять его!
Мне нравится когда комментарии отвечают на вопрос “Почему?”, а не “Как?”. Такие комментарии, действительно не раз сэкономили бы мне время. Бывает, смотришь на чужой код, и в голове мысль “Почему так? Можно же проще!”, а через пол часа понимаешь, что да, именно так. Проще не получится. Программируя, мы часто натыкаемся на различные подводные камни, которые тем или иным образом влияют на наш код. Если вы выбираете не самое очевидное и простое решение — не поленитесь описать почему вы так поступили.
Итого.
Как всегда, оба мнения имеют право на существование. Если интересно мое: “Код, который может вызвать затруднение, нуждается в комментарии”. Если кто-то будет уверять, что комментарии — зло, я не буду спорить, но останусь при своем мнении. Самое главное, если вы решили отказаться от комментариев, убедитесь, что причина в понятном и логичном коде, а не в банальной лени.
Автор: voff
