Документирование программной архитектуры

(в соавторстве с Феликсом Бахманом, Дэвидом Гарланом, Джеймсом Аймерсом, Ридом Литтлом, Робертом Нордом и Джудит Стеффорд)'

Книги — как пчелы, разносящие живительную пыльцу мысли от одного человека к другому.

Джеймс Рассел Лоуэлл

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

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

На материале настоящей главы вы узнаете, какую именно информацию об архитектуре следует вносить в ее документацию, и ознакомитесь с методами ее фиксации. Кроме того, мы обсудим существующие в настоящее время нотации, в том числе UML.

Варианты применения архитектурной документации

Характер архитектуры любой системы обусловливается предъявляемыми к ней требованиями; это утверждение справедливо и по отношению к документации архитектуры — другими словами, содержание документации зависит от предполагаемых вариантов ее применения. Документация ни при каких обстоятельствах не может быть универсальной. С одной стороны, она должна быть абстрактной и, следовательно, доступной для понимания новыми сотрудниками, но с другой — весьма детальной — настолько, чтобы ее можно быть использовать как план проведения анализа. Между архитектурной документацией, предназначенной, скажем, для проведения анализа безопасности, и архитектурной документацией для изучения конструкторами должны существовать серьезные различия. С другой стороны, у этих вариантов будет мало общего с содержанием руководства для ознакомления, предназначенного новому сотруднику.

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

Из всего этого следует, что заинтересованные в составлении документации лица преследуют разные цели — от представленной в ней информации они требуют разной направленности, разных уровней детализации и разных трактовок. Предполагать, что один и тот же архитектурный документ будет одинаково воспринят всеми без исключения заказчиками, наивно. Стремиться следует к тому, чтобы любое заинтересованное лицо смогло быстро найти необходимую информацию, как можно меньше в процессе ее поиска натыкаясь на незначительные (с его точки зрения) сведения.

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

Согласно одному из фундаментальных правил технической документации в общем и документации программной архитектуры в частности, составитель должен принимать позицию читателя. Без труда составленная, но трудная для восприятия (с точки зрения читателя — в данном случае заинтересованного лица) документация не найдет себе применения.

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

Среди заинтересованных лиц встречаются как умудренные опытом люди, гак и новички. Информация, которая им нужна, отличается не по содержанию, а по детализации — новичку она потребуется в «облегченном» виде. Архитектурная документация должна успешно вводить в курс дела всех, у кого есть такая потребность: новых разработчиков, инвесторов, временных участников проекта и т. д.

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