Це погана практика не видаляти зайві файли відразу з VCS, а замість цього спочатку позначити їх як "Для видалення" з коментарями?

Мені хотілося дізнатись, чи можна вважати поганою практикою спосіб поводження з вихідними файлами, який потрібно видалити з контролю версій.

Я хочу пояснити це на основі цього прикладу:

Нещодавно я дуже розгнівався, тому що мені довелося нудно розбирати класи Java в програмі, яка в основному була мертвим кодом, однак вона ніде не була задокументована, а також не коментувалася в цих класах Java. Звичайно, їх потрібно було видалити, але перед тим, як видалити такі зайві речі, у мене є - дехто може сказати дивний - звичка:

Я не видаляю такі зайві файли одразу через SVN-> Delete (замінюю командою delete вашої системи контролю версій за вибором), але натомість розміщую коментарі у тих файлах (я маю на увазі і в голові, і в нижньому колонтитулі), до яких вони збираються бути видаленим + моє ім'я + дата, а також, що ще важливіше - ЧОМУ ВІДКРИТИ (у моєму випадку, тому що вони були мертві, заплутаний код). Потім я зберігаю і зобов’язую їх до контролю версій. Наступного разу, коли мені доведеться зробити / перевірити щось у проекті для контролю версій, я натискаю SVN-> Delete, а потім вони в кінцевому підсумку видаляються у версії Control - все одно, звичайно, можна відновлювати через перегляди, і саме тому я прийняв цю звичку.

Навіщо це робити, а не видаляти їх відразу?

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

"Гм ... чому були видалені ці файли? Я раніше добре працював." (Натискає "повернути" -> хлопець, який повернувся потім, назавжди відсутній або недоступний протягом наступних тижнів, і наступний правонаступник повинен дізнатися, як я, про що ці файли)

Але ви не помічаєте, чому ці файли були видалені з повідомлень про фіксацію?

Звичайно, я є, але повідомлення про прихильність інколи колеги не читають. Це не типова ситуація, коли ви намагаєтесь зрозуміти (в моєму випадку мертвий) код, що ви спочатку перевіряєте журнал контролю версії з усіма пов'язаними повідомленнями комісії. Замість того, щоб повзати через журнал, колега може відразу побачити, що цей файл марний. Це економить її / його час, і вона / він знає, що цей файл, ймовірно, був відновлений погано (або, принаймні, це викликає питання.

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

З точки зору сторонньої людини, ця методологія, схоже, вкорінена в дуже консервативному погляді на управління джерелами.

"Що робити, якщо я видаляю цей невикористаний файл, а потім комусь це потрібно?" хтось може запитати.

Ви використовуєте управління джерелом. Скасуйте зміни, а ще краще поговоріть із особою, яка видалила файл (надіслати повідомлення).

"Що робити, якщо я видаляю мертвий файл, то хтось знову починає його використовувати, і вони вносять зміни?" хтось ще може запитати.

Знову ж, ви використовуєте управління джерелом. У вас виникне конфлікт злиття, який людина повинна вирішити. Відповідь тут, як і на останнє запитання, - це спілкування зі своїми товаришами по команді.

Якщо ви дійсно сумніваєтесь, файл слід видалити, повідомте його перед тим, як видалити його з керування джерелом. Можливо, його лише нещодавно перестали використовувати, але можлива його функція. Ви цього не знаєте, але, можливо, хтось із інших розробників.

Якщо його потрібно зняти, вийміть його. Виріжте жир з кодової основи.

Якщо ви зробили "oopsie" і файл вам справді потрібен, пам’ятайте, що ви використовуєте управління джерелом, щоб ви могли відновити файл.

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

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

Це обґрунтована порада. Огляди коду повинні вловлювати подібні речі. Розробникам потрібно звертатися до повідомлень про фіксацію, коли у файл внесено несподівану зміну або файл видалено або перейменовано.

Якщо повідомлення про фіксацію не розповідають історію, тоді розробникам також потрібно писати краще повідомлення про фіксацію.

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

• Відсутність точних оглядів коду
• Відсутність розуміння того, як працює управління джерелами
• Відсутність командного спілкування
• Погані повідомлення з боку розробників

Ці проблеми потрібно вирішити, тому вам не здається, що ви кидаєте скелі у скляний будинок, коли ви видаляєте код або файли.

Так, це погана практика.

Ви повинні розмістити пояснення щодо видалення у повідомленні про фіксацію, коли ви здійснюєте видалення файлів.

Коментарі у вихідних файлах повинні пояснювати код таким, яким він виглядає . Повідомлення комітів повинні пояснювати, чому зміни в комісії були внесені, тому історія фіксації у файлі пояснює його історію.

Написання коментарів, що пояснюють зміни безпосередньо у самому джерелі, просто зробить код набагато складнішим. Подумайте над цим: Якщо ви коментуєте файл щоразу, коли ви змінюєте чи видаляєте код, незабаром файли будуть заповнені коментарями щодо історії змін.

На мою думку, обидва варіанти не найкраща практика , на відміну від поганої практики:

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

Моя вподобана практика - багато в чому через те, що протягом декількох років була укушена, маючи на увазі, що ви не завжди знаєте, де чи ким використовується ваш код - це:

1. Додайте коментар, вказуючи, що це кандидат для видалення та депресія #warning або подібне, (більшість мов мають такий механізм, наприклад, на Java , у гіршому випадку printбуде достатньо твердження або подібного), в ідеалі з певним часовим шкалою та з контактними даними. Це попередить усіх, хто все ще фактично використовує код. Ці попередження зазвичай знаходяться всередині кожної функції або класу, якщо такі речі існують .
2. Через деякий час оновіть попередження до стандартної області файлу #warning(деякі люди ігнорують попередження про депрекацію, а деякі ланцюжки інструментів не попереджують подібні попередження)
3. Пізніше замініть область файлу #warningна #errorеквівалентну - це порушить код під час збирання, але при необхідності може бути видалений, але особа, що видаляє його, не зможе проігнорувати. (Деякі розробники не читають і не звертаються до будь-яких попереджень або їх стільки, що вони не можуть відокремити важливі).
4. Нарешті позначте файли (файли) (на дату або після закінчення дати) як видалені у ДКС.
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: видаліть файл і скопіюйте

Якщо це мертвий код, видаліть його. Кому-небудь це потрібно, він може повернутися назад, але крок перейменування не дозволить їм використовувати його безпосередньо, не замислюючись.

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