Кофе-брейк #20. Что такое legacy-код и как с ним работать. Инструменты, которые облегчают написание технической документации

What такое legacy-code и How с ним работать

Источник: Dou Рано и поздно программисту наверняка придется встретиться с legacy-codeом. Whatбы облегчить последствия этого знакомства, я подобрал несколько практических советов и примеров из собственного опыта — в частности, работы с унаследованной Java-системой.

Особенности legacy

Legacy (наследство) — это чужой code, который часто бывает ужасен настолько, что оказывается вообще непонятно, How с ним работать. И если вам придется работать с legacy-системой, кроме старого codeа вы также встретитесь:

• с устаревшей технологией;
• неоднородной архитектурой;
• недостатком or даже полным отсутствием documentации.

На самом деле, legacy-code — это не так уж страшно, и вот почему: если система жила все эти десять лет и до сих пор работает, значит, Howой-то толк от нее есть. Может быть, она приносит хорошие деньги (в отличие от вашего последнего стартапа). Кроме того, этот code относительно надежен, если он смог так долго выживать в продакшене. Поэтому вносить в него изменения нужно с осторожностью. Прежде всего, нужно понять две вещи:

1. Мы не можем неуважительно относиться к системе, которая зарабатывает миллионы, or к которой обращаются тысячи людей в день. Как бы плохо она ни была написана, этот отвратительный code дожил до продакшена и работает в режиме 24/7.

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

Обратный инжиниринг

Для успешной работы с legacy-codeом придется пользоваться приемами reverse engineering. Для начала, нужно внимательно читать code, чтобы точно понимать, How именно он работает. Это обязательно, ведь documentации у нас, скорее всего, не будет. Если мы не поймем хода мыслей автора, будем делать изменения с непредсказуемыми последствиями. Whatбы обезопасить себя от этого, нужно вникать еще и в смежный code. И при этом двигаться не только вширь, но и вглубь. Откуда вызывается метод с ошибкой? Откуда вызывается вызывающий его code? В legacy-проекте «call hierarchy» и «type hierarchy» используется чаще, чем что-либо еще. Придется провести много времени с отладчиком: во-первых, чтобы находить ошибки, и, во-вторых, чтобы понять, How все работает. What касается documentации, не лишним будет прибегнуть к промышленной археологии. Очень полезно бывает откопать где-нибудь старую documentацию и поговорить с теми, кто помнит, How писался доставшийся вам code. Используя эти приемы, рано or поздно вы начнете более or менее понимать code. Но чтобы ваши усorя не пошли прахом, вы должны обязательно сразу же documentировать результаты своих изысканий. Для этого я советую рисовать блок-схемы or диаграммы последовательности (sequence diagrams). Конечно, вам будет лень, но делать это точно нужно, иначе через полгода без documentации вы сами в этом codeе будете копаться How в первый раз.

Не переписывайте code

Самое важное в процессе разработки — вовремя бить себя по рукам и не пытаться переписать весь code заново. Прикиньте, сколько человеко-лет для этого потребуется. Вряд ли заказчик захочет потратить столько денег на переделывание того, что уже и так работает. Это касается не только системы в целом, но и любой ее части. Вам, конечно, могут дать неделю на то, чтобы во всем разобраться, и еще неделю на то, чтобы что-то исправить. Но вряд ли дадут два месяца на написание части системы заново. Вместо этого реализуйте новый функционал в том же стиле, в Howом написан остальной code. Иными словами, если code старый, не стоит поддаваться соблазну использовать новые красивые технологии: такой code потом будет очень тяжело читать. Например, вы можете столкнуться с ситуацией, которая была у нас: часть системы написана на Spring MVC, а часть — на голых сервлетах. И если в части, написанной на сервлетах, нужно дописать еще что-то, то дописываем мы это так же — на сервлетах.

Соблюдайте бизнес-интересы

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

Тестируйте

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

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

И только после прохождения всех этих трех фаз мы можем делать релиз. Кто-то наверняка считает, что сертификация — лишняя фаза, так How на стадии стабorзации все уже выяснено, но наш опыт говорит о том, что это не так: иногда во время регрессионного теста, который прогоняется по второму кругу на другой машине, что-нибудь да вылезет.

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

Релизная proceduresа может быть, например, следующей. Когда заканчивается разработка и пройдены две or три фазы тестирования, мы пишем письмо DevOps-команде за 36 часов до предполагаемого времени релиза. После этого созваниваемся с девопсами и обсуждаем все изменения окружений (мы сообщаем им обо всех изменениях в БД и конфигурации). На каждое изменение у нас есть document (тикет в Jira). Затем во время релиза все причастные к этому собираются вместе, и каждый говорит, что он сейчас делает: «Мы залor базу», «Мы перезапустor такие-то serverы», «Мы пошли прогонять регрессионные тесты в рабочем окружении». Если же что-то идет не так, запускается proceduresа отката релиза, точно описанная в изначальном documentе на релиз — без такого documentа мы обязательно что-нибудь забудем or напутаем.

Контролируйте качество codeа

И наконец, code review — практика, к которой прибегают почему-то далеко не во всех проектах. Очень хорошо, если каждая часть codeа проверяется более чем одним человеком. Даже в очень сильной команде в процессе code review обязательно обнаруживаются Howие-то косяки, а если смотрят несколько человек, количество выявленных косяков возрастает. Причем иногда самое страшное находит третий or четвертый ревьюер.

Инструменты, которые облегчают написание технической documentации

Источник: Dzone Большинство программистов не любят писать техническую documentацию. Эксперт по психологии Джеральд Вайнберг даже назвал documentацию «касторовым маслом программирования»: разработчики любят ее читать, но сами писать просто ненавидят. Отсутствие руководства or пустая дорожная карта приводят к нехватке информации о том, How работают различные части программного обеспечения. В конечном итоге это ухудшает восприятие ситуации конечными пользователями codeа, поскольку при отсутствии documentации они не могут полагаться на точность и полезность продукта. Whatбы программисту было легче сформировать у себя привычку писать documentацию, я рекомендую обратить внимание на четыре отличных инструмента, доступных сейчас практически каждому.

GitHub Pages

Сегодня, вероятно, нет ни одного разработчика, который не имел бы опыта работы в GitHub. Кроме того, это отличное место для программистов, которым нужно где-то хранить documentацию. Многие используют стандартный Readme в своей codeовой базе, чтобы предоставить пользователю простое практическое руководство, но это не единственный способ создания documentации на GitHub. Используя GitHub Pages, вы получаете не только хостинг для страниц своего проекта, включая documentацию и руководства. Вы получаете возможность напрямую взаимодействовать со всеми репозиториями GitHub, что позволяет разработчикам обновлять documentацию так же, How они обновляют свой code. Более того, здесь вы можете использовать Jekyll — он помогает преобразовать разметку в виде обычного текста or в полноценные веб-pages.

Read the Docs

Как следует из названия, Read the Docs предоставляет разработчикам платформу для хранения и чтения documentации. Сервис работает примерно так же, How GitHub Pages: программисты могут вносить изменения в documentацию из своих любимых систем контроля версий, включая Git, Bazaar, Mercurial и других. Также поддерживается автоматическая обработка версий и создание страниц. Лучшая часть Read Docs — это его гибкость. Он поддерживает веб-хуки, поэтому можно автоматизировать большую часть процесса создания documentов. Это огромная экономия времени при выполнении задачи, с которой большинство программистов вообще не хотят иметь ничего общего. Кроме того, все, что размещено на платформе, доступно для широкой публики в различных форматах, включая PDF, одностраничный HTML и даже формат электронных книг. Сервис берет на себя значительную часть рутинной работы по поддержанию актуальности documentации.

Tettra

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

Apiary

What делает Apiary такой полезной для разработчиков, так это тот факт, что она отлично помогает с documentированием API. Платформа позволяет пользователям писать свою documentацию в Markdown, включая ложные вызовы API. Также Apiary позволяет провести тестирование и прототипирование элементов API. Иными словами, это инструмент создания documentации и платформа тестирования в одном месте.