Кава-брейк #20. Що таке legacy-код та як з ним працювати. Інструменти, що полегшують написання технічної документації

Що таке legacy-код і як з ним працювати

Джерело: Dou Рано і пізно програмісту, напевно, доведеться зустрітися з legacy-кодом. Щоб полегшити наслідки цього знайомства, я підібрав кілька практичних порад та прикладів із власного досвіду — зокрема роботи з успадкованою Java-системою.

Особливості legacy

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

• із застарілою технологією;
• неоднорідною архітектурою;
• недоліком чи навіть повною відсутністю документації.

Насправді, legacy-код — це не так страшно, і ось чому: якщо система жила всі ці десять років і досі працює, значить, якась користь від неї є. Можливо, вона приносить добрі гроші (на відміну від вашого останнього стартапу). Крім того, цей код є відносно надійним, якщо він зміг так довго виживати в продакшені. Тому вносити до нього зміни потрібно з обережністю. Насамперед, потрібно зрозуміти дві речі:

1. Ми не можемо зневажливо ставитися до системи, яка заробляє мільйони, або до якої звертаються тисячі людей на день. Як би погано вона не була написана, цей огидний код дожив до продакшена і працює в режимі 24/7.

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

Зворотній інжиніринг

Для успішної роботи з legacy-кодом доведеться скористатися прийомами reverse engineering. Для початку потрібно уважно читати код, щоб точно розуміти, як саме він працює. Це обов'язково, адже документації ми, швидше за все, не матимемо. Якщо ми не зрозуміємо ходу думок автора, робитимемо зміни з непередбачуваними наслідками. Щоб убезпечити себе від цього потрібно вникати ще й у суміжний код. І при цьому рухатися не лише вшир, а й углиб. Звідки викликається метод із помилкою? Звідки викликається код, що викликає? У legacy-проекті "call hierarchy" і "type hierarchy" використовується частіше, ніж будь-що ще. Доведеться провести багато часу з відладчиком: по-перше, щоб знаходити помилки, і, по-друге, щоб зрозуміти, як усе працює. Щодо документації, не зайвим буде вдатися до промислової археології. Дуже корисно буває відкопати десь стару документацію і поговорити з тими, хто пам'ятає, як писався код, що дістався вам. Використовуючи ці прийоми, рано чи пізно ви почнете більш менш розуміти код. Але щоб ваші зусилля не пішли прахом, ви повинні обов'язково відразу документувати результати своїх пошуків. Для цього я раджу малювати блок-схеми чи діаграми послідовності (sequence diagrams). Звичайно, вам буде ліньки, але робити це точно потрібно, інакше через півроку без документації ви самі в цьому коді копатиметеся як вперше. Для цього я раджу малювати блок-схеми чи діаграми послідовності (sequence diagrams). Звичайно, вам буде ліньки, але робити це точно потрібно, інакше через півроку без документації ви самі в цьому коді копатиметеся як вперше. Для цього я раджу малювати блок-схеми чи діаграми послідовності (sequence diagrams). Звичайно, вам буде ліньки, але робити це точно потрібно, інакше через півроку без документації ви самі в цьому коді копатиметеся як вперше.

Не переписуйте код

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

Дотримуйтесь бізнес-інтересу

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

Тестуйте

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

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

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

Формалізуйте DevOps та реліз

Релізна процедура може бути, наприклад, наступною. Коли закінчується розробка та пройдено дві чи три фази тестування, ми пишемо лист DevOps-команді за 36 годин до передбачуваного часу релізу. Після цього зідзвонюємося з девопсами та обговорюємо всі зміни оточення (ми повідомляємо їм про всі зміни в БД та конфігурації). На кожну зміну ми маємо документ (тикет в Jira). Потім під час релізу всі причетні до цього збираються разом, і кожен каже, що він зараз робить: «Ми залабо базу», «Ми перезапустабо сервери», «Ми пішли проганяти регресійні тести в робочому оточенні». Якщо ж щось іде не так, запускається процедура відкату релізу, точно описана у первісному документі на реліз — без такого документа ми обов'язково щось забудемо чи наплутаємо.

Контролюйте якість коду

І, нарешті, code review — практика, до якої вдаються чомусь далеко не у всіх проектах. Дуже добре, якщо кожна частина коду перевіряється більш ніж однією людиною. Навіть у дуже сильній команді в процесі code review обов'язково виявляються якісь косяки, а якщо дивляться кілька людей, кількість виявлених косяків зростає. Причому іноді найстрашніше знаходить третій чи четвертий ревьюєр.

Інструменти, що полегшують написання технічної документації

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

GitHub Pages

Сьогодні, ймовірно, немає жодного розробника, який не мав би досвіду роботи у GitHub. Крім того, це чудове місце для програмістів, яким потрібно десь зберігати документацію. Багато хто використовують стандартний Readme у своїй кодовій базі, щоб надати користувачеві простий практичний посібник, але це не єдиний спосіб створення документації на GitHub. Використовуючи GitHub Pages , ви отримуєте не тільки хостинг для сторінок свого проекту, включаючи документацію та посібники. Ви отримуєте можливість безпосередньо взаємодіяти з усіма репозиторіями GitHub, що дозволяє розробникам оновлювати документацію так само, як вони оновлюють свій код. Більше того, тут ви можете використовувати Jekyll— допомагає перетворити розмітку у вигляді звичайного тексту або на повноцінні веб-сторінки.

Read the Docs

Як випливає з назви, Read the Docsнадає розробникам платформу для зберігання та читання документації. Сервіс працює приблизно так само, як GitHub Pages: програмісти можуть вносити зміни до документації зі своїх улюблених систем контролю версій, включаючи Git, Bazaar, Mercurial та інші. Також підтримується автоматична обробка версій та створення сторінок. Найкраща частина Read Docs – це його гнучкість. Він підтримує веб-хуки, тому можна автоматизувати більшу частину процесу створення документів. Це величезна економія часу у виконанні завдання, з якою більшість програмістів взагалі хочуть мати нічого спільного. Крім того, все, що розміщено на платформі, доступне для широкої публіки у різних форматах, включаючи PDF, односторінковий HTML і навіть формат електронних книг.

Tettra

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

Apiary

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