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

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

Наприклад, GUI повинен був бути тонким шаром, без ділової логіки. Це мені сказали. Реалізація містить багато логіки.

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

Отже, де я повинен описати ці проблеми? Програмне забезпечення для відстеження помилок? Або я повинен описати відхилення впровадження від архітектури в документі, що описує архітектуру системи?

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

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

Наприкінці дня проектний документ повинен слугувати керівництвом коду. Якщо документ не допомагає новому розробнику зрозуміти поточний стан бази коду та його структурування, тоді документ не корисний.

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

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

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

Формалізуючи архітектуру системи, важливо, щоб ви розуміли не тільки значення, яке архітектура внесе до столу, а й розуміти та оцінювати, якою вона має бути.

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

Про нефункціональні вимоги:

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

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

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

Для створення авторитетної архітектури програмного забезпечення дійсно потрібно 3 речі.

Декларативний

Це частина документації, де ви декларуєте НЕ ЩО ТАКЕ, а як ОБОВ'ЯЗКОВО. Ми робимо це завдяки використанню різних архітектурних поглядів системи. Ми визначаємо компоненти, які мають бути, як вони взаємодіють, а потім необов'язково детально переглядаємо кожен компонент для отримання більш детальних подань, які заявляють, як повинна бути спроектована система.

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

Обґрунтування

Обґрунтування вашої архітектури програмного забезпечення - це те, що забезпечує легітимність та повноваження прийнятим архітектурним рішенням. Можливо, було прийнято рішення використовувати слухач подій Pub / Sub через MQ для запуску пакетного завдання, і ви його діаграмуєте?

Чому було прийнято таке рішення? Ми пояснюємо, чому в розділі "Обгрунтування" і пов'язуємо наше пояснення з нефункціональними вимогами, цілями атрибутів якості або архітектурно значущими вимогами. (Наприклад, завдання повинні бути асинхронними та повторюваними. Обслуговуваність як атрибут якості призводить до того, що у разі відмови пакетної роботи завдання можуть бути повторно ініційовані за допомогою MQ-повідомлення. Система повинна мати нульову втрату повідомлення з асинхронним зв’язком тощо. ..)

Ризики

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

(Напр., Перевірка валідації на стороні клієнта коду JavaScript на стороні клієнта. Це порушення принципу DRY, і це суперечить атрибуту якості технічного обслуговування. У цій області немає визначених нефункціональних вимог навколо продуктивності, тому там немає обґрунтування для поточної поведінки системи)

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

Вам дійсно потрібно вирішити, чи слід документувати поточну структуру проекту, чи бажану структуру проекту, або те і інше.

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

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

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

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

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

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

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

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

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