Комментирование и системы контроля версий
Сегодня хотел бы обсудить ситуацию, в которой комментарии в исходном коде используются в качестве некоторой псевдо-системы контроля версий. А именно, когда при помощи комментариев "удаляется" какой-то уже неиспользуемый код.
Ситуация эта выглядит примерно так. Программисту хочется внести какое-то изменение в код, и он поступает следующим образом: комментирует старый кусок, а затем вставляет на его место исправленный. Таким образом в исходном файле остаются ОБА куска кода одновременно.
Мне кажется, что такой способ комментирования плох в двух смыслах.
- Данный вид комментирования представляет собой подмену (причём недостаточно функциональную) системы контроля версий.
- Данный вид комментирования неудобен для тех, кто будет разбираться в коде после вас.
В чем состоит подмена? В том, что система контроля версий как раз и предназначена для того, чтобы дать возможность увидеть кто, когда, зачем и каким именно способом изменил данный кусок кода. Комментирование только дублирует информацию уже имеющуюся в системе контроля версий, причём не всю её (подобные комментарии обычно ведь не стандартизированы - что захочет там разработчик написать, то и напишет). Таким образом подобные комментарии являются избыточными.
Неудобство для "будущих поколений"
Подобные комментарии, помимо того что являются избыточными (с чем довольно легко можно смириться), могут также являться источником дополнительных сложностей для программистов, которые не являются авторами первоначального кода.
Дело в том, что подобные закомментированные и давно неиспользуемые куски:
- При исследовании кода методом поиска :-) могут вполне попасться в результаты, а значит придётся затратить дополнительное время на их изучение
- При интенсивном использовании сильно замусоривают код, что также создаёт дополнительные сложности
- Комментарии многими воспринимаются как пояснение относительно работы данного куска кода (и правильно воспринимаются, именно для этого комментарии и нужны). Поэтому закомментированная часть кода, если комментарий был использован вместо системы контроля версий, может вызвать у читающего затруднения с пониманием - зачем здесь комментарий? может быть кто-то что-то тестировал и забыл убрать комментарий? Короче говоря, возникает лишний повод задуматься.
Мой общий вывод из вышеизложенного такой (нагло подделываясь под классика):
"Commenting code out considered harmful". Неиспользуемый код нужно удалять, а не комментировать. Конечно, всегда бывают "ситуации" и мы здесь говорим о каком-то общем, "среднем" случае.
P.S. Да, современные интегрированные среды разработки позволяют достаточно легко бороться с перечисленными выше недостатками (outlining; поиск с использованием регулярных выражений; интеллектуальный поиск, понимающий что комментарии нужно пропускать). Но они же часто содержат функции, позволяющие вообще не заниматься подобным комментированием, например IntelliJ Idea содержит замечательную функцию Local History, являющуюся по сути постоянно включённой системой контроля версий.
А самое главное - зачем создавать проблемы, чтобы потом их решать, у нас ведь и так есть чем заняться?
blog: 
LinkedIn
Мой Круг
4 комментария:
Кстати, совсем все не так бесспорно, как мне кажется. Да коментарение кода замусоривает, и такие да, частично это является заменой системы контроля версий. Однако, и в моей практике встречались ситуации, когда временное комментирование кода это лучший выбор. Повторюсь – именно временное. И уж конечно такие куски не должны попадать в релизную версию. Для чего применим – допустим человек пишет какое то решение, однако, с течением времени он понимает, что оно не идеально.. или возможно не работает как надо, а для его доведения требуется потратить осмысленное время. Разработчик начинает искать другие варианты решения, изменяя или переписывая кусок кода. Причем зачастую принципиально. А как мы помним – одним из постулатов системы контроля версий должно быть то, что в нее кладут ТОЛЬКО работающий и проверенный код. Противоречие, однако. Другими словами первоначальный код не должен был попасть в систему контроля версий.
Коментарение кода один из способов возможности отката к прошлому решению, если выясняется, что как не казалось в процессе разработки, новое решение еще хуже.
Еще пример, он конечно менее показателен, и его можно обойти действительно хорошей документацией, но…
Был кусок кода, который был написан по всем правилам, и вроде бы должен был работать, но… в какой-то момент выясняется, что это не так. Приходится реализовать какое-то решение, которое с первого взгляда, кажется хуже, но работает. Так вот, закоментареный кусок кода, с пояснениями, почему пошли другим путем, а не классическим, причем именно в месте его нахождения поможет в дальнейшем избегнуть соблазна попасть в ситуацию «Кто это писал? Все переписать, на….» и сделать по правильному.
Да, документирование может решить туже задачу, однако увидев «плохой» кусок кода, Вам, возможно в последнюю очередь захочется лезть в систему контроля версий для того, чтоб прояснить ситуацию….
На самом деле я больше соглашусь со вторым возражением чем с первым :-)
Дело в том, что мне не кажется что в систему контроля версий можно класть ТОЛЬКО рабочий код. Вот здесь я писал об этом. Нет никакой проблемы в том чтобы класть в систему контроля версий и эксперименты. Вопрос в том куда именно в системе контроля версий это класть.
Насчёт второго примера - да, я согласен очень часто увидеть "версионную" информацию (кто написал, когда, почему закомментировал) прямо в коде существенно быстрее чем "лезть" в систему контроля версий. Тут у меня есть два соображения:
1) Я не утверждаю догматично что код надо всегда стирать. Я лишь считаю что каждый конкретный случай его комментирования должен быть "исключительным"
2) Я замечал, что часто нежелание "лезть" в систему контроля версий связано с абсолютно не имеющими отношения к делу вещами, например: по каким-то причинам система контроля версий очень медленно работает или скажем есть некоторый недостаток знакомства с системой, что не позволяет использовать её эффективно. То есть проблема на самом деле может быть совершенно в другом.
Так или иначе я ни в коем случае не предлагаю единый рецепт для решения всех проблем. Я предлагаю так сказать "practice" (надеюсь что best :-)) - то есть вещи которые можно и нужно нарушать, но только если ты осознаешь зачем это делается.
готов убивать на месте за commenting out code, если нужны эксперименты заведи себе в системе контроля версий ветку, но только не надо этих комментариев. Принимаю, только как очень временное решение, потому что есть сейчас проект, где закомментированные куски кода иногда размером больше чем код. Приходится разбираться и в них, прежде чем вносить изменения, и слишком часто оказывается что этот код давно и никому не нужен, а зачистить его уже непонятно как, вроде как боязно а вдруг понадобиться? Просто человек не знал что такое система контроля версий.
Iv пишет...
готов убивать на месте за commenting out code, если нужны эксперименты заведи себе в системе контроля версий ветку, но только не надо этих комментариев.
Мда,.. вот это наболело... сочувствую. Однако, пожалуй убивать все ж не стоит :)
во первых бесполезно, его , убитого, старые коменты кто вычищать то будет ?
а во вторых – лучше раз убедить и получить союзника, чем насиловать кого бы то нибыло :)
ЗЫ Отступление лирическое, но не менее важное. Если ты сможешь убедить человека в правильности той или иной методологии и с тобой согласятся, есть вероятность, что она действительно хороша на практике. Мой препод в институте говорил: “Хочешь понять какую то науку, разобраться в проблеме – прочти по этой теме лекцию :). (что, кстат и предлагал сделать нам:)
Так что не надо крови! Давайте жить дружно! :)))
Отправить комментарий