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

За время работы над этим проектом я собрал всю информацию, необходимую для написания документа. Поскольку я также добавил некоторые функции, я выделил некоторые фрагменты кода, которые явно нарушают архитектуру, как она описана.

Например, GUI должен был быть тонким слоем, без бизнес-логики. Это то, что мне сказали. Реализация содержит много логики.

Мой начальник поручил мне написать документ с описанием архитектуры системы. Целевая аудитория - текущие и будущие разработчики, работающие над проектом. Мне нужно описать, что должно быть, но мне также нужно как-то описать отклонения.

Итак, где я должен описать эти проблемы? Программное обеспечение для отслеживания ошибок? Или я должен описать отклонения реализации от архитектуры в документе, описывающем архитектуру системы?

Если вы документируете проект или архитектуру системы, которая уже была построена, документ должен описывать ее как созданную, а не как разработанную или как предназначенную. Если в архитектуре есть странности или несоответствия, то в этом документе должны быть названы эти проблемы и как можно более подробно объяснены читателю.

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

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

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

Если вам нужен совет по созданию архитектуры, мне нравится подход, предложенный в стандарте IEEE 1016-2009 «Стандарт IEEE для информационных технологий - проектирование систем - описание разработки программного обеспечения» . Это обеспечивает разумную структуру для описания проекта, которое может использоваться для сбора как архитектурной, так и подробной информации о проекте.

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

При формализации архитектуры системы важно, чтобы вы понимали не только то значение, которое лежит в основе архитектуры, но также понимали и ценили то, чем она должна быть.

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

По нефункциональным требованиям:

Нефункциональное требование - это требование, которое определяет критерии, которые можно использовать для оценки работы системы, а не для конкретного поведения. Они контрастируют с функциональными требованиями, которые определяют конкретное поведение или функции. План выполнения функциональных требований подробно описан в проекте системы. План реализации нефункциональных требований подробно описан в архитектуре системы.

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

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

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

декларативный

Это часть документации, в которой вы заявляете НЕ ЧТО ТАКОЕ, а как вещи ДОЛЖНЫ БЫТЬ. Мы делаем это с помощью различных архитектурных представлений системы. Мы определяем компоненты, которые должны быть, как они взаимодействуют, и затем мы дополнительно углубляемся в каждый компонент для более детальных представлений, которые объявляют, как должна быть разработана система.

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

обоснование

Обоснование вашей архитектуры программного обеспечения - это то, что обеспечивает легитимность и авторитетность принятых архитектурных решений. Возможно, было принято решение использовать прослушиватель событий Pub / Sub поверх MQ для запуска пакетного задания, и вы это представляете?

Почему было принято это решение? Мы объясняем, почему в разделе «Обоснование», и связываем наше объяснение с нефункциональными требованиями, целями атрибутов качества или архитектурно значимыми требованиями. (Например, задания должны быть асинхронными и повторяемыми, ремонтопригодность как атрибут качества определяет, что в случае сбоя пакетного задания задания могут быть повторно инициированы через сообщение MQ, система должна иметь нулевую потерю сообщения при асинхронной связи и т. Д. ..)

риски

Теперь, когда вы объявили, какой должна быть архитектура, и подтвердили ее с помощью своего Обоснования, теперь вы можете идентифицировать Риски для текущего состояния системы, где это не соблюдается.

(Например, проверка на стороне сервера дублируется на коде Javascript на стороне клиента. Это нарушение принципа СУХОЙ, и это противоречит качественному признаку ремонтопригодности. В этой области не определены функциональные требования к производительности, поэтому Обоснование текущего поведения системы)

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

Вам действительно нужно решить, должны ли вы документировать текущую структуру проекта или желаемую структуру проекта, или и то, и другое.

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

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

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

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

Я был бы склонен написать архитектурный документ, организованный в 3 основных раздела.

Первое знакомство с дизайном / архитектурой, которая была изначально задумана. Это позволит новым разработчикам / читателям получить представление о том, что должна делать система, и, очевидно, должно быть привязано к требованиям / сценариям использования и т. Д.

Второй раздел должен объяснить очень ясно , что именно архитектура на самом деле является. Это позволяет новым разработчикам / читателям получить представление о текущем состоянии дел и о том, с чем они имеют дело, если они смотрят на программное обеспечение (и, возможно, другую документацию). В этом разделе должно быть четко указано различие между тем, что было задумано, и реальностью, так как это, скорее всего, высветит вещи, которые либо очень неправильны в исходной архитектуре (надеюсь, не слишком много!), И области, где ярлыки / хаки (вероятно, довольно немного, если бы было была оказана большая нагрузка на команду разработчиков), и требования не выполняются, или программное обеспечение начинает выглядеть «плохо» разработанным, то есть хрупким, нестабильным, непереносимым.

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

Я думаю, что это охватывает (на высоком уровне) то, что должно быть захвачено. То, как вы делаете это с точки зрения подразделов документа или программного обеспечения для отслеживания ошибок, которое вы используете, зависит от домена, в котором вы работаете / личные предпочтения / размер команды / бюджет / шкала времени и т. Д.