Это плохая практика, чтобы не удалять избыточные файлы сразу из VCS, а вместо этого помечать их как «Для удаления» с комментариями в первую очередь?

53

Я хотел знать, можно ли считать, что мой подход к исходным файлам, которые необходимо удалить из системы контроля версий, считается плохой практикой.

Я хочу объяснить это вам на основе этого примера:

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

Я не удаляю такие избыточные файлы сразу через SVN-> Delete (замените их командой delete из выбранной вами системы контроля версий), но вместо этого помещаю комментарии в эти файлы (я имею в виду как в верхнем, так и в нижнем колонтитуле), которые они собираются быть удаленным + мое имя + дата, а также - что более важно - ПОЧЕМУ ОНИ УДАЛЕНЫ (в моем случае, потому что они были мертвы, запутанный код). Затем я сохраняю и фиксирую их для контроля версий. В следующий раз, когда мне нужно зафиксировать / зарегистрировать что-либо в проекте для контроля версий, я нажимаю SVN-> Удалить, а затем они в конечном итоге удаляются в Версионном контроле - все еще, конечно, восстанавливаемым посредством ревизий, и именно поэтому я принял эту привычку.

Зачем делать это, а не удалять их сразу?

Моя причина в том, что я хочу иметь явные маркеры, по крайней мере, в последней ревизии, в которой существовали эти избыточные файлы, поэтому они заслуживают удаления. Если я удалю их сразу, они будут удалены, но нигде не задокументировано, почему они были удалены. Я хочу избежать типичного сценария, подобного этому:

«Хм… почему эти файлы были удалены? Я раньше работал нормально». (Прессы 'revert' -> парень, который вернулся, исчез навсегда или не будет доступен в течение следующих недель, и следующий сотрудник должен утомительно, как и я, выяснить, о чем эти файлы)

Но разве вы не замечаете, почему эти файлы были удалены в сообщениях о коммите?

Конечно, я делаю, но сообщение о коммите иногда не читается коллегами. Это не типичная ситуация, когда вы пытаетесь понять (в моем случае мертвый) код, что вы сначала проверяете журнал контроля версий со всеми связанными сообщениями фиксации. Вместо того, чтобы просматривать журнал, коллега сразу же видит, что этот файл бесполезен. Это экономит ее / его время, и она / он знает, что этот файл, вероятно, был восстановлен плохо (или, по крайней мере, это поднимает вопрос.

Брудер Люстиг
источник
120
По сути, вы пытаетесь повторить работу вашей системы контроля версий прямо в файле. Делая это, я бы поднял флаг в моей голове. Если ваши коллеги не читают сообщения фиксации, и они воскрешают файл, который был по праву удален и проходит проверку кода, в вашей команде определенно что-то не так, и это прекрасная возможность научить их лучше.
Винсент
6
@GregBurghardt Это похоже на хороший вопрос о плохой идее. Может быть, люди голосуют против на основании второй части этого (когда, IMO, они должны голосовать за первую)?
Бен Ааронсон
13
«В следующий раз, когда мне нужно что-то зафиксировать / зафиксировать в проекте для контроля версий, я нажимаю SVN-> Удалить». Вы говорите, что удаляете их в (потенциально) совершенно не связанной фиксации?
Кевин
21
Конечно, я делаю, но сообщение о коммите иногда не читается коллегами. - если они не проверяют сообщение о коммите, можно предположить, что их не интересует, почему файл был удален ... в противном случае им следует проверить сообщение о коммите.
Муравей P
9
Если я хочу узнать, почему файл исчез из моей проверки VCS, я сначала посмотрю в истории изменений , и если это ничего не объясняет, я прочитаю обсуждение, которое произошло, когда удаление проверялось. (Если у вас нет процесса проверки кода, через который проходит каждое изменение, у вас возникают более серьезные проблемы.) И если это все еще не помогает, я поговорю с тем, кто удалил файл. Я мог бы взглянуть на прежнее содержимое файла, чтобы попытаться выяснить, что он делал раньше, но не для объяснения удаления.
Звол

Ответы:

110

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

С точки зрения постороннего, эта методология, кажется, коренится в очень консервативном взгляде на контроль источников.

«Что делать, если я удалю этот неиспользуемый файл, а потом он кому-нибудь понадобится?» кто-то может спросить.

Вы используете контроль версий. Отмените изменение или, еще лучше, поговорите с человеком, который удалил файл (общаться).

«Что, если я удалю мертвый файл, тогда кто-то снова начнет его использовать, и они внесут изменения?» кто-то еще может спросить.

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

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

Если это должно быть удалено, удалите это. Вырежьте жир из базы кода.

Если вы сделали «oopsie» и вам действительно нужен файл, помните, что вы используете систему контроля версий, чтобы вы могли восстановить файл.

Винсент Савард в комментарии к вопросу сказал:

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

Это здравый совет. Обзоры кода должны ловить такие вещи. Разработчики должны обращаться к сообщениям о коммитах, когда в файл вносится непредвиденное изменение или файл удаляется или переименовывается.

Если сообщения коммита не рассказывают историю, то разработчикам также нужно лучше писать сообщения коммита.

Боязнь удалить код или удалить файлы указывает на более глубокую, системную проблему с процессом:

  • Отсутствие точного кода отзывов
  • Недостаток понимания того, как работает система контроля версий
  • Недостаток командного общения
  • Плохие коммиты со стороны разработчиков

Это проблемы, которые нужно решить, поэтому вы не чувствуете, что бросаете камни в стеклянный дом при удалении кода или файлов.

Грег Бургхардт
источник
3
«Предположение, что если разработчики не читают сообщения о фиксации, они обязательно прочитают комментарии в исходном коде». Я думаю, что это довольно хорошее предположение. Разработчик, изменяющий файл, должен фактически посмотреть на файл, чтобы выполнить задачу, в то время как нет ничего, что заставляло бы его смотреть на историю контроля версий.
AShelly
7
@AShelly: задача разработчика - редко менять комментарий. Задачи включают изменение кода, на котором сосредоточен разработчик, а не комментарии.
Грег Бургхардт
21
@AShelly То, что им нужно открыть файл, не означает, что они прочтут конкретный комментарий вверху. Целевая аудитория для этого изменения - самый забывчивый разработчик, тот, кто считает, что их потребности - единственные потребности, и все должно вращаться вокруг них. Они вряд ли прочитают ваш вежливый комментарий. Хуже того, они, скорее всего, прочитают его, а затем просто вернутся к следующей самой старой версии.
Cort Ammon
5
@AShelly - в качестве примера я обычно открываю файлы в определенном месте. В VS я могу открыть метод напрямую, используя раскрывающиеся списки вверху или контекстное меню «перейти к определению». Я бы никогда не увидел верхнюю часть файла. Также в Sublime Text я часто открываю строку. Их открытый диалог users.rb: 123 откроет users.rb прямо в строке 123. Многие редакторы кода имеют очень похожие параметры.
Котейр
2
В дополнение к вышесказанному, чем сложнее выполнять подобные задачи, тем меньше вероятность того, что люди будут выполнять их регулярно. Если вы можете сделать это проще, это снижает «энергию активации» для вас и всех остальных. Это особенно важно, если вы пытаетесь поощрять изменение практики для других членов команды. Чем сложнее процедура, тем сложнее получить вступительный взнос.
xdhmoore
105

Да, это плохая практика.

Вы должны поместить объяснение для удаления в сообщение фиксации, когда вы фиксируете удаление файлов.

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

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

JacquesB
источник
6
Возможно, добавьте ответ на вопрос: это плохая практика? Да, потому что ....
Хуан Карлос Кото
1
Я иногда делаю то же самое (как OP), потому что это легче раскомментировать, чем вернуться. В редких случаях, даже если код компилируется и проходит автоматическое тестирование, существует причина существования того кода, который я упустил из виду, что ручной тестировщик обнаружит. В этом редком сценарии вместо того, чтобы проходить через большую боль или возвращать вещи через несколько коммитов позже, я просто раскомментирую код обратно (и возвращаюсь к тому, как его можно улучшить)
Андрей Савиных,
2
@AndrewSavinykh Это другое, вы комментируете код, который все еще не уверены, что хотите удалить.
Прекратить причинять вред Монике
6
@AndrewSavinykh «Большая боль или возвращение вещей через несколько коммитов позже» - интересно, какой контроль версий вы используете; это не должно быть основной болью. Это, конечно, не в Git, по крайней мере, после того, как вы сделали это пару раз и узнали, на что обращать внимание ... и при условии, что ваша история не изобилует ненужными коммитами туда-сюда, которые дают вам конфликтует каждое другое слияние. И коммиты, которые просто комментируют что-то, довольно склонны делать это ...
leftaroundabout
4
@AndrewSavinykh да, и не похоже, чтобы у меня не было таких проблем - проекты, сопровождающие которых никогда не работали с контролем версий и помещали много комментариев в комментарии, которые должны были быть сообщениями о коммитах, вместо этого добавили новые инструкции по ручному откатыванию. правильного возврата и т. д. Получившееся состояние репозитория создавало массу удовольствия от конфликта в каждой более крупной перебазировке ... Но, и это моя точка зрения, эти проблемы часто в основном вызваны обходными путями, такими как тот, который вы защищаете здесь.
оставил около
15

На мой взгляд, оба ваших варианта не являются лучшей практикой , в отличие от плохой практики:

  1. Добавление комментариев только добавляет какое-либо значение, если кто-то прочитает эти комментарии.
  2. Простое удаление из VCS (с указанием причины в описании изменения) может повлиять на критически важные результаты, и многие люди не читают описание изменения, особенно в условиях давления.

Моя любимая практика - в основном из-за того, что за эти годы ее укусили несколько раз, учитывая, что вы не всегда знаете, где и кем используется ваш код, - это:

  1. Добавьте комментарий о том, что он является кандидатом на удаление, а также на устаревший #warning или аналогичный (большинство языков имеют такой механизм, например, в Java , в худшем случае достаточно printоператора или аналогичного), в идеале с некоторой шкалой времени и с контактными данными. Это предупредит любого, кто все еще использует код. Эти предупреждения обычно находятся внутри каждой функции или класса, если такие вещи существуют .
  2. Через некоторое время обновите предупреждение до стандартного объема файла #warning(некоторые люди игнорируют предупреждения об устаревании, а некоторые цепочки инструментов по умолчанию не отображают такие предупреждения).
  3. Позже замените область файла #warningна #errorили эквивалентную - это нарушит код во время сборки, но при необходимости может быть удалено, но лицо, удаляющее его, не сможет его игнорировать. (Некоторые разработчики не читают и не обращаются ни к каким предупреждениям или имеют так много, что они не могут выделить важные).
  4. Наконец отметьте файл (ы), (в срок или после даты выполнения), как удаленный в VCS.
  5. При удалении всего пакета / библиотеки / и т. Д. На этапе предупреждения я бы добавил файл README.txt или README.html или аналогичный с информацией о том, когда и почему планируется избавиться от пакета и оставить только этот файл с изменить, чтобы сказать, когда он был удален, в качестве единственного содержимого пакета в течение некоторого времени после удаления остального содержимого.

Одним из преимуществ этого подхода является то, что некоторые системы контроля версий (CVS, PVCS и т. Д.) Не удаляют существующий файл при оформлении заказа, если он был удален в VCS. Это также дает добросовестным разработчикам, тем, кто исправляет все свои предупреждения, много времени для решения проблемы или обжалования удаления. Это также вынуждает остальных разработчиков, по крайней мере, посмотреть на уведомление об удалении и много жаловаться .

Обратите внимание, что #warning/ #error- это механизм C / C ++, который вызывает предупреждение / ошибку, за которым следует предоставленный текст, когда компилятор встречает этот код, java / java-doc имеет @Deprecatedаннотацию для выдачи предупреждения об использовании & @deprecatedдля предоставления некоторой информации и т. Д. Рецепты, чтобы сделать подобное в Python, и я видел, assertкак предоставлять аналогичную информацию #errorв реальном мире.

Стив Барнс
источник
7
В частности, поскольку в этом вопросе упоминается Java, используйте @deprecatedкомментарий JavaDoc и @Deprecatedаннотацию .
200_success
8
Это кажется более подходящим, если вы хотите избавиться от чего-то, что еще используется. Предупреждение может сохраняться до тех пор, пока не исчезнут все случаи использования, но как только код станет мертвым, его следует немедленно удалить.
Энди
6
@Andy Одна из проблем с кодом библиотечного типа, особенно в Open Source или в крупных организациях, заключается в том , что вы можете подумать, что код мертв, но обнаружите, что он активно используется в одном или нескольких местах, которые вы лично никогда не представляли что он использовался. Иногда код нужно убить, потому что он действительно плохой или содержит риски для безопасности, но вы просто не знаете, где и где он используется.
Стив Барнс
1
@ 200_success спасибо - мой фон в C / C ++ показывает - добавил к ответу.
Стив Барнс
1
@SteveBarnes Возможно, но это не то, о чем спрашивает ОП. Он подтвердил, что код мертв.
Энди
3

Да, я бы сказал, что это плохая практика, но не потому, что это в файлах, а в сообщении фиксации. Проблема в том, что вы пытаетесь внести изменения, не общаясь с вашей командой.

Всякий раз, когда вы вносите какие-либо изменения в ствол - добавляя, удаляя или изменяя файлы любым способом - вы должны, прежде чем вернуться к стволу, поговорить об этих изменениях непосредственно с членом (или членами) группы, который будет непосредственно знающие о них (по сути, обсудите, что вы бы поместили в эти заголовки непосредственно со своими товарищами по команде). Это гарантирует, что (1) действительно удаляемый код необходимо удалить, и (2) ваша команда будет с большей вероятностью узнавать, что код удален, и, таким образом, не будет пытаться отменить удаление. Не говоря уже о том, что вы также получите обнаружение ошибок и тому подобное для кода, который вы добавляете.

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

Если вы не хотите идти так долго без фиксации (т. Е. Ваше изменение имеет смысл в виде нескольких ревизий), рекомендуется создать ветку из ствола и зафиксировать ветку, а затем объединить ветку обратно в ствол, когда изменение готово. Таким образом, VCS все еще выполняет резервное копирование файла для вас, но ваши изменения никак не влияют на транк.

TheHansinator
источник
1

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

Итак (в проекте C ++) я добавил

#error this is not as dead as I thought it was

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

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

JDługosz
источник
-1

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

Но этот код не должен жить долго. Я вообще удаляю в начале следующего спринта.

Если у вас есть коллеги, которые не читают сообщения коммитов или не спрашивают вас, почему вы оставили код в проекте, тогда ваша проблема не в плохом стиле кодирования. У тебя другая проблема.

Тони Эннис
источник
это , кажется, не предлагает ничего существенного по точкам сделанных и разъяснено в предыдущих 6 ответов
комар
-3

Вы также можете реорганизовать класс и переименовать его с префиксом UNUSED_Classname, прежде чем тянуть трюк. Тогда вы должны напрямую зафиксировать операцию удаления

  • Шаг 1: переименовать класс, добавить свой комментарий, зафиксировать
  • Шаг 2: удалить файл и зафиксировать

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

Также научите людей, как просматривать все сообщения коммитов для файла, некоторые люди даже не знают, что это возможно.

user275398
источник
6
«Рефакторинг» на самом деле не означает, что вы думаете
Nik
6
Нет необходимости переименовывать класс / метод, чтобы гарантировать, что он не используется, удаление его работает так же хорошо. Вместо этого процедура аналогична любым другим изменениям: 1) удалить мертвый код , 2) запустить тесты , 3) если они пройдут, зафиксировать с комментарием .
Шверн
1
@ user275398 Я также думаю, что переименование файлов - это слишком много. Кроме того, с технологической точки зрения SVN рассматривает переименование так, как если бы файл удалялся и создавался с новым именем, таким образом, у вас есть разрыв в истории. Если вы восстановите переименованный файл и посмотрите его в журнале SVN, история до переименования будет недоступна. Для этого вам нужно вернуть файл со старым именем. Рефакторинг - это, кстати, нечто иное, рефакторинг - это организация существующего кода в новую структуру.
Брудер Люстиг
@BruderLustig: Хорошее программное обеспечение, безусловно, этого не сделает. Git имеет git mv, который отслеживает историю. Ртутный также имеет hg mv. Похоже, svn moveдолжно работать и для SVN?
wchargin
@wchargin Нет, git mvпросто перемещает файл и выполняет этапы удаления и создания файла. Все отслеживание движения происходит, когда вы бегаете git log --followи тому подобное. gitне может отслеживать переименования, фактически не отслеживает изменения ; вместо этого он отслеживает состояния во время фиксации и выясняет, что изменилось в то время, когда вы просматриваете историю.
Maaartinus