Як модернізувати легасі-код. Організаційні аспекти рефакторингу

Привіт! Я Дмитро Ханджанов, Front-end розробник команди MOJAM. Наш продукт — це платформа для кіберспортсменів і гравців у CS2, яка налічує понад 4 мільйони користувачів зі 168 країн світу, де на перше місце ставиться інтерактивність, реактивність і відмовостійкість системи.

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

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

Майлстоуни

Треба з чогось розпочинати, тому створюємо покроковий план реалізації рефакторингу:

1. Формулювання ідеї. Ідея повинна бути сформульована в письмовому вигляді, окреслювати конкретні цілі та описувати засоби їх досягнення. Така документація допоможе рухатися далі й продавати ідею менеджменту.

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

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

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

5. Створення плейграунду. Закладання основних механізмів, які забезпечуватимуть працездатність застосунку на новій архітектурі. Так почнеться перенесення наявного функціоналу на нові рейки.

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

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

Продаж ідеї менеджменту

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

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

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

Аргументи для продажу ідеї

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

Неможливість тестувати проєкт

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

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

Реальні приклади негативного досвіду

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

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

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

Кількість та якість аргументів

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

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

Складність проєкту, що виходить з-під контролю

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

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

Повірте, менеджери завжди краще розуміють проблеми, коли вони виражені в грошовому еквіваленті. І така статистика допоможе перетворити фразу «зростає складність проєкту» в реальні цифри.

Якщо такої статистики немає, пояснити проблему менеджменту буде досить складно, адже тоді менеджерам доведеться покладатися на «чесне слово» тімліда... І якщо ви на аутстафі або аутсорсі, тоді у мене для вас погані новини.

Задоволення запитів команди

Виніс цю думку окремим пунктом. Вона не очевидна і її не складно продати, але, на мою думку, вона розумна та справедлива.

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

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

Авторитетність при продажу ідеї

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

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

Супутня документація

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

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

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

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

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

Робота з командою. Пояснення нових концепцій

Цей пункт стосується переважно Front-end розробки через різноманітність підходів, які використовуються в проєктах. Не секрет, що у Front-end приходять як люди, що пройшли «найкращі у світі курси — за два тижні з нуля у Senior Front-end», так і спеціалісти з профільною освітою. Тому різниця в стилі написання коду може варіюватися від спагетті-коду на умовному React до якогось самописного патерну MVC в ООП-стилі для організації бізнес-логіки.

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

Для себе я виробив тактику «презентацій». Коли рефакторю дуже невелику частину проєкту, роблю слайди, які показують, як вона працює, як нею користуватися і які у неї є правила. Важливо спланувати ряд презентацій за різними напрямами, необхідних для пояснення команді, і записати їх. Щоб у майбутньому мати можливість ділитися такими презентаціями з новачками.

Прийняття конвенцій

Конвенції — красиве слово, що замінює собою «домовленості», які команда приймає для того, щоб виробити єдиний код-стайл на проєкті. Звичайно, більшість правил (відступи між дужками або іменування змінних) можна і потрібно задати правилами ESLint, але ці правила досить обмежені.

Розробники, накопичуючи досвід, виробляють свої власні звички в написанні коду. Хтось віддає перевагу використанню об’єктів як списків ключ-значення, а хтось використовує для цього мапи. Хтось віддає перевагу поверненню кортежів, а хтось групує їх в об’єкт. Прикладів безліч.

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

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

Реалізація

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

Створення playground

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

Тому важливо сконцентруватися на базових речах. На прикладі нашого «абстрактного проєкту» було б недоречно починати переносити код у модулі, однак основну увагу варто приділити створенню middleware як основній цінності рефакторингу. Також хорошою ідеєю буде створення модуля як приклад для колег.

Важливо пам’ятати, що більшу частину часу займе рев’ю цього рішення ними. Рев’ю буде необхідне як для ознайомлення з кодом, так і для уточнювальних питань та правок. Змін буде багато, тому враховуйте, що 20-30% часу піде на їх перегляд.

Поступове перенесення проєкту

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

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

Тестування системи

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

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

Висновок

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

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