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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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в реальном мире.

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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