Кращі практики передачі застарілого кодексу

Через пару місяців колега перейде до нового проекту, і я успадкую один з його проектів. Щоб підготуватися, я вже наказав « Ефективно працювати Майклом Пером зі спадщиною» .

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

Деякі твори коду, який я буду успадковувати:

• Це функціонує: помилок невідомо, але оскільки вимоги до продуктивності продовжують зростати, деякі оптимізації стануть необхідними в не надто віддаленому майбутньому.
• Незадокументовано: Існує майже нульова документація на рівні методу та класу. Що, як передбачається, робить код на більш високому рівні, добре зрозуміло, тому що я вже багато років пишу проти його API (як чорна скринька).
• Тільки тести інтеграції вищого рівня: Існують лише тести інтеграції, які перевіряють належну взаємодію з іншими компонентами через API (знову ж таки, чорна скринька).
• Дуже низький рівень, оптимізований для швидкості: Оскільки цей код є центральним у всій системі додатків, багато його було оптимізовано кілька разів протягом багатьох років і є надзвичайно низьким рівнем (одна частина має власний менеджер пам'яті для певних структур / записи).
• Одночасне і без блокування: Хоча я дуже добре знайомий з одночасним і без замком програмуванням і фактично внесли в цей код кілька фрагментів, це додає ще один рівень складності.
• Велика база даних: Цей конкретний проект налічує більше десяти тисяч рядків коду, тому я не зможу все пояснити мені.
• Написано в Delphi: Я просто збираюся викласти це там, хоча я не вважаю, що мова є германною до питання, оскільки я вважаю, що цей тип проблеми є мовно-агностичним.

Мені було цікаво, як найкраще витратити час до його від'їзду. Ось пара ідей:

• Отримайте все, що можна побудувати на моїй машині: Хоча все слід перевіряти у контролі вихідного коду, хто не забув раз у раз перевіряти файл, тож, мабуть, це буде першим замовленням у бізнесі.
• Більше тестів: Хоча я хотів би більше тестів на рівні класу, щоб, коли я буду вносити зміни, будь-які помилки, які я ввів, можна було потрапити на ранній стадії, код, як зараз, не перевіряється (величезні класи, довгі методи, занадто багато взаємні залежності).
• Що потрібно документувати: Я думаю, що для початківців було б найкраще зосередити документацію на тих областях коду, які інакше було б важко зрозуміти, наприклад, через їх низький рівень / дуже оптимізований характер. Я боюся, що там є кілька речей, які можуть виглядати некрасиво і потребують рефакторингу / переписування, але насправді є оптимізаціями, які були там з вагомою причиною, яку я можу пропустити (пор. Джоел Спольський, речі , які тобі слід Ніколи не роби, Частина I )
• Як документувати: Я думаю, що найкращі діаграми класів архітектури та послідовності діаграм критичних функцій, які супроводжуються деякою прозою, були б найкращими.
• Кого документувати: Мені було цікаво, що було б краще, щоб він написав документацію чи попросив його пояснити мені, щоб я міг написати документацію. Я боюся, що речі, які для нього очевидні, але не мені, інакше не будуть висвітлені належним чином.
• Рефакторинг за допомогою парного програмування: Це може бути неможливо зробити через обмеження часу, але, можливо, я міг би відновити деякий його код, щоб зробити його більш рентабельним, поки він все ще був, щоб подати інформацію про те, чому все є таким, яким вони є.

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

Оновлення: Коли проект здачі завершено, я розширив цей список, маючи власний досвід у цій відповіді нижче .

Отримавши доступ до розробника, ви запитаєте код:

• Які модулі було найскладніше кодувати / реалізувати. Які були проблеми і як їх подолали.

• Які модулі генерували найбільше помилок.

• Які модулі призвели до найскладніших помилок.

• Якими бітами коду він найбільше пишається.

• Які біти коду він хотів би рефафікувати, але не мав часу.

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

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

• Отримайте все під контролем версій: Переконавшись, що все, що мені потрібно було створити, знаходилось під контролем версій, я також шукав на жорсткому диску старого розробника, щоб шукати додаткові сценарії чи утиліти, які були б корисні для розгортання та / або тестування програми, але не були не зареєстровано.
• Зверху вниз: я б почав з високого рівня погляду на основні класи та екскурсії з давнім розробником основних районів. Тоді я б самостійно заглиблювався в решту, позначаючи речі, які не мали сенсу для мене //TODOмаркерами.
• Напишіть всю документацію самостійно: Хоча я старий розробник переглядав моє написання, щоб переконатися, що я правильно це зробив, я наполягав на тому, щоб все написати самостійно. Таким чином я був би впевнений, що написання мало сенс для мене, а не лише для старого розробника.
• Коментарі скрізь: я додав резюме документації XML до кожного класу та кожного методу. Таким чином я переконався, що принаймні переглянув кожен фрагмент коду і маю достатньо розуміння, щоб узагальнити те, що він робив у реченні. Це також полегшило розуміння методів використання методів / класів узагальнення, оскільки IntelliSense збирає цю інформацію. Я також міг легко визначити області коду, які мені все-таки доводилося дивитись.
• Документ, близький до джерела: Щоб полегшити зв’язок між вихідним кодом та документацією, я розміщую більшість моєї документації прямо у вихідному коді. Для документації високого рівня, яка описує взаємодію між різними підсистемами, я використовував вікі, оскільки розміщення цієї інформації лише в одному місці в коді не працювало. Вся документація повинна бути електронною та повнотекстовою.
• Діаграми: Для базового огляду я використовував діаграми класів різних деталей для різних підсистем. Для паралельних частин діаграми об'єктів та взаємодії були дуже корисними; дивіться також моє інше запитання по темі .
• Рефакторинг як пара: Хоча я робив рефакторинг зі старим розробником, щоб зрозуміти код і зробити речі більш рентабельними, це був трудомісткий і також ризикований процес через відсутність хороших інструментів рефакторингу та купу неприємних залежності серед різних частин. Ефективна робота Майкла Пір'єса зі спадщинним кодексом - це справді хороша допомога для цього, хоча рефакторинг без належної підтримки інструменту все ще болісний. Під час рефакторингу я дозволив би йому керувати мишею та клавіатурою, оскільки це було йому веселіше (див. Також мою останню точку кулі), і я міг записати те, що я навчався.
• Окремі реєстрації для коментарів та змін: Після того, як я випадково ввів помилку, написавши коментар через override, я обережно робив коментарі та зміни в окремих реєстраціях. Я використовував невелику утиліту, щоб викреслити всі коментарі з вихідного коду, перш ніж щось перевірити, тому різниця в реєстрації, що стосується лише коментарів, показала б 0 відмінностей. Всі зміни (наприклад, видалення невикористаних полів) ретельно перевіряли зі старим розробником, щоб переконатися, що я не видаляв речі, які все ще потрібні.
• Покрокове проходження критичних уривків: Для найбільш оптимізованих / складних уривків я б переходив код по черзі зі старим розробником, а іноді навіть із третім колегою. Таким чином я отримав глибоке розуміння коду, і оскільки більшість людей перевіряли код, ми фактично визначили кілька помилок, а також деякі речі, які можна було б оптимізувати.
• Будьте швидкі і нехай мотивує старого розробника: я помітив, що старий розробник все менше цікавився, оскільки його останній день наближався (не дивно). Тому я би переконався, що найважливіші частини були передані першими, а решту я залишив для себе, якщо потрібно. Я також намагався залишити йому кумедніші речі (наприклад, керування клавіатурою при програмуванні пари) і робити нудні речі, такі як написання документації.
• Визначте запити щодо функцій. Мені було корисно попросити старого розробника про список функцій, про які запитували люди, але вони ще не додані. Було кілька речей, які мені здалися простими додати, але там, де була вагома причина, щоб вони не були додані, оскільки вони порушили б інші речі, коли реалізувались так, як я спочатку подумав.

Потрапивши в подібну ситуацію, я вважаю, що також варто було б врахувати наступне:

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

  (Це може не стосуватися вас, наприклад, якщо ви вже робите безперервну інтеграцію або безперервне впровадження, але це варто згадати, про всяк випадок ...)

• Написання додаткових тестів: Це дійсно хороший спосіб перевірити своє розуміння системи. Це дасть змогу (або змусить) уважніше придивитися до областей коду, або підтвердить, що код настільки ж без помилок, як ви підозрюєте, або виявить області, де ви думали, що розумієте намір, але насправді ви перед тим, як він піде, потрібно попросити у колеги роз'яснень

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

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

Щодо Refactoring, що використовує парне програмування , єдине, що я б сказав, є небезпека, що це може стати ямою без дна, особливо з огляду на те, що ви сказали, що у вас є лише тести високого рівня. Ви можете виявити, що це закінчується, використовуючи більше доступного часу, ніж ви планували.

+1 за відповіді, які ви вже маєте у своєму запитанні!

Керована екскурсія
10k рядків коду - це багато, але я думаю, що все ще не неможливо, щоб інший хлопець дав вам "екскурсію". Ви сідаєте разом перед кодом, і він веде вас у подорож зверху вниз, працюючи вниз по «шарах». Вам знадобиться це зробити короткими поривами - все одним ходом убило б вас обох.

Збільшити, зменшити масштаб
Перевага цього полягає в тому, що, коли він пояснює це вам, у нього майже напевно будуть деякі "о, так, є і це" моменти, яких він може не мати, якби він просто намагався його документувати сам по собі. І ваші запитання допоможуть зосередитись на очевидних для нього, але не для кого-небудь бітах. Така взаємодія масштабування / зменшення масштабу можлива лише один на один, намагаючись написати або прочитати щось подібне, що є непростим.

Документація.
Я думаю, що ви повинні самостійно документувати речі - він повинен починатися знизу (якщо ви не встигнете зібратися туди), а ви повинні почати зверху, виходячи з того, що ви зрозуміли його екскурсія, і ніби це було для когось іншого [на попередній роботі я успадкував вантаж "спадщини" коду, і тільки що встиг задокументувати його, перш ніж покинути себе :)].

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

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

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

Ставтесь до передачі, як до проекту, і складіть план та залучайте управління.

0 - Переконайтеся, що ви знаєте, як користуватися системою.

1 - Складіть чіткий опис компонентів розчину, джерела кожного та де він лежить (у різних сховищах)

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

3 - Отримуйте ліцензії кожного зовнішнього компонента, крім випадків, коли він виходить за межі вашої сфери (наприклад, спеціальні dlls, база даних тощо)

4 - Отримайте письмовий звіт про поточний стан системи від розробника та ваших клієнтів (якщо вони локальні для вашої компанії)

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

6 - Отримайте перелік запланованих заходів (щомісячні виконання завдань, щотижневі виконання завдань), на які програмне забезпечення має відповідати

7 - Вивчіть процедури резервного копіювання / відновлення

8 - Розуміти рамки, які використовуються для створення програми

9 - Ознайомтесь із запитуваними / очікуваними / запланованими модифікаціями та статусом будь-яких запитів на очікування користувачів. Почніть намагатися визначити, як це зробити самостійно.

10 - Переконайтесь, що середовище для тестування та розробки дуже схоже.

11 - Спробуйте визначити основні залежності (від інших систем або між компонентами), які неможливо легко помітити.

12 - Визначте та задокументуйте необхідні версії кожного використання програмного забезпечення та його контакт з постачальником (якщо необхідно)

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

14 - Отримайте системний потік високого рівня. і почніть створювати свою бібліотеку документації

15 - Зрозумійте, як керувати безпекою користувачів програми

16 - Отримайте журнал помилок і спробуйте зрозуміти дії та як дія вплинула на старіші дані (якщо це застосовується)

17 - Знайте процеси, які займають занадто багато часу, і на що потрібно стежити (наприклад, незвичні розміри файлів, ftp дублікатів файлів тощо), де це можливо.

18 - Перевірте годинник виробничого сервера

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

20 - Отримайте контактну інформацію цього хлопця

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

22 - Оцініть своє розуміння за 1 тиждень до того, як він піде, і повідомте про будь-які проблеми, які ви бачите як ризик

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

Удачі.

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

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

Потім документуйте все, що залишилося.

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

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

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

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

Ідея полягає в тому, щоб спочатку повністю зрозуміти код (за його присутності), а потім написати / зробити все, що дасть змогу пізніше (за його відсутності).

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

Нарешті, після того, як ви зробите вищезазначене, активно берете на себе контроль. Вирішіть самі, для яких деталей вам потрібно покриття одиничного тесту. які деталі потрібно оптимізувати (чи можна) оптимізувати, як можна відредагувати якийсь компонент тощо. Довіртеся, що якщо ви знаєте систему, ви зможете приймати всі рішення, як тільки його не буде.

Я відчуваю тебе.

Кілька пропозицій:

1. Запишіть кожну розмову, яка ведеться з програмістом, що йде!
2. Попросіть мотивацію, що стоїть за "великими" питаннями. Добре, що ви розумієте API, але шукайте внутрішні рішення - чому код поділився таким, яким він є? які обов'язки.
3. Докладіть зусиль, щоб справді вивчити код. Коли ви берете на себе обов'язки з технічного обслуговування та підтримки, іноді виникає тиск "вивчити код під час прогресу". Опірте, якщо можете, і дійсно вивчіть код.
4. Шукайте сценарії. Ви знаєте API - подивіться, як поводиться код. Приклад, який спадає на думку, - це модуль факсу. Як користувач API, вам попередньо потрібно було підготувати зображення сторінки та надіслати код командою для передачі сторінки. Попросіть програмувача, що виїжджає, простежити з вами код, щоб побачити, як проходить цей сценарій. Тоді, звичайно, перейдіть до сценарію "отримання".
5. 80/20 - спробуйте спочатку висвітлити більш поширені сценарії.
6. Розглянемо перезапис. Якщо код старий і інтерфейси чітко визначені, можливо, технологія досить змінилася, щоб виправдати його.
7. Я ненавиджу це говорити, але думаю розшукати нову роботу.

Якщо ви хочете, щоб пристойну документацію досить безболісно придбали копію програми Pascal Analyzer (PAL), я використав це для проектів Delphi, і це було чудово - вони, можливо, тепер розділили функціональність документації на продукт, з яким я не знайомий (браузер Pascal) тож вам, можливо, доведеться купувати і те, і інше (<300 USD), але PAL був чудовим інструментом для розуміння того, де використовуються змінні, де викликуються функції з тощо та вибирає всілякі потенційні проблеми з кодом.

Використовуйте PAL, щоб отримати уявлення про те, як структурований код плюс, ймовірно, список з приблизно 1000 запропонованих удосконалень, якщо мій досвід хотів би продовжувати. Опрацювання списку поліпшить якість коду, значно спростить його та полегшить ваше життя на майбутнє. Сама Delphi підтримує рефакторинг в останніх версіях (останні 5 років або близько того). Вам потрібно було включити все у файл dpr, щоб він справді працював належним чином, коли я це робив, тому майте це на увазі.

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

Хоча ви і не згадували про резервну базу даних, але припускаючи, що є така, яку вам слід

1. Отримайте документальну модель документації, особливо стовпці та PK-FK
2. Налаштування сліду sql та записуйте всі запити, які запускаються під час використання програми. Порядок виконання запитів дасть вам хороше уявлення про потік програми, а також допоможе у налагодженні

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

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

1) (Технічна особа) Контактні дані клієнтів, з якими він має справу.

2) Його рахунок, за яким він купував ліцензії на програмне забезпечення, ключі, які потрібно поновлювати щороку, і процеси / витрати на їх поновлення.

3) Документ про налаштування сторонніх бібліотек / компонентів програмного забезпечення та продуктів, які інтегруються з вашими продуктами. Ми боролися протягом 4 днів, щоб повернути машину, яка була втрачена через ІТ-очищення простору та деякі неправильні інструкції, передані їм.

4) Документи / кроки, які він використовується для депонування вихідного коду компаніям, депозитним програмним забезпеченням, наприклад, Escrow.

5) Є ще довгий список, але він може не застосовуватись і до вас. Жодна документація не може замінити реальну людину, тому зберігайте його деталі під рукою, будьте в хороших стосунках та удачі :)

Також я не знаю, чи це вам перший раз. Для мене я працював з 5/6 роботодавців і завжди успадковував код з поганою документацією або взагалі відсутністю документації. Тож разом з усією документацією просто залишайтеся позитивними :)