Машинний переклад (marian з Tatoeba en-uk).
Документування рішень архітектури
Michael Nygard - 15 листопада 2011
Швидка архітектура
Контекст
Архітектура гнучких проектів має бути описана і визначена по- різному. Не всі рішення будуть прийматися одночасно, і всі вони не будуть виконуватися на початку проекту.
Агресивні методи не є проти документації, але лише до порожньої документації. Документи, які допомагають команді, можуть мати значення, але лише якщо ці методи зберігаються до сьогодні. Великі документи ніколи не зберігаються до сьогодні. Малі, модульні документи мають хоча б шанс на оновлення.
Крім того, ніхто ніколи не читав великих документів. Більшість розробників працювали принаймні на одному проекті, де документ специфікації був більшим (у байтах) за загальний розмір коду. Ці документи є завеликими для відкриття, читання або оновлення. Елементи розмірів для всіх заповнювачів легше використовувати.
Однією з найвагоміших речей, за якими слід стежити протягом життя проекту, є мотивація певних рішень. Нова особа, яка приходить до проекту, може бути збентежена, збентежена, в захваті або розлючена колишнім рішенням. Не розуміючи раціональності або наслідків, ця особа має лише два варіанти:
1. - Сліпо приймайте рішення.
Відповідь на це питання може бути нормальною, якщо рішення все ще є коректним. Можливо, це не дуже добре, але якщо контекст було змінено і рішення слід переглянути. Якщо у проекті накопичується забагато рішень, які приймаються без розуміння, команда розробників боїться щось змінити, а проект зазнає краху під власною вагою.
2. Сліпо поміняйте його.
Знову ж таки, це може бути нормально, якщо рішення треба скасувати. З іншого боку, зміна рішення, не розуміючи його мотивації або наслідків, може призвести до пошкодження загальної вартості проекту, не усвідомлюючи цього (наприклад, рішення підтримало недіяльну вимогу, яка ще не була випробувана.)
Краще уникати або сліпого сприйняття, або завернення сліпоти.
Рішення
Ми триматимемо збірку записів для "архітектурно значущих" рішень: тих, що впливають на структуру, нефункціональні характеристики, залежності, інтерфейси, або технології будівництва.
Запис про рішення архітектури - це короткий текстовий файл у форматі, подібному до александрійського візерунка. (Хоч самі рішення не обов' язково є шаблонами, вони мають однаковий баланс сил.) Кожен запис описує набір сил і єдине рішення у відповідь на ці сили. Зауважте, що у цьому полі рішення є центральним елементом, отже специфічні сили можуть з' явитися у декількох ARDS.
Ми збережемо ADR у сховищі проекту під doc/ Arch/adr-NN.md
Ми повинні використовувати невибагливу мову форматування тексту, таку як Markdown або Textile.
АДР буде пронумеровано послідовно і монотонально. Числа не буде використано повторно.
Якщо рішення відмінне, ми будемо тримати стару, але вважати її за заміну. (До цих пір важливо знати, що це було рішення, але це вже не рішення.)
Ми використаємо формат з декількома частинами, тому кожен документ легко перетравлювати.
У цих документах є назви, що є короткими іменниками. Наприклад, " ADR 1: Deployment on Ruby on Rails 3. 0. 0 " або " ADR 9: LDAP для інтеграції з декількома значеннями "
Контекст У цьому розділі описано сили гри, зокрема технологічні, політичні, соціальні та локальні проекти. Ймовірно, ці сили знаходяться у напрузі, їх слід викликати так. Мова у цьому розділі має значення. У ній просто описуються факти.
Рішення У цій секції описує нашу відповідь на ці сили.
Статус Можна " пропонувати ," якщо заповнювачі проекту ще не погодилися з ним, або " прийняти " після згоди. Якщо пізніше ADR змінить або скасує рішення, його можна позначити як " застарілий " або " перевизначений " з посиланням на його заміну.
Наслідки У цьому розділі описано остаточний контекст після застосування рішення. Всі наслідки має бути наведено у цьому розділі, а не лише "позитивні". У окремому випадку можуть бути позитивні, негативні і нейтральні наслідки, але всі вони впливають на команду і проект у майбутньому.
Весь документ має бути однією або двома сторінками. Кожен з них напишеться так, наче це розмова з майбутнім розробником. Для цього потрібен чудовий стиль запису, повноцінні речення впорядковані у абзаци. Позначки можна використовувати лише для візуального стилю, а не як виправдання написання фрагментів речення. (Кулі вбивають людей, навіть кулі PowerPoint.)
Стан
Прийнято.
Наслідки
Один ADR описує одне важливе рішення для конкретного проекту, яке має вплинути на те, як проходитимуть інші проекти.
Наслідки одного з ADR дуже ймовірно, що вони стануть контекстом наступних ADR. Це також подібно до ідеї Александра про шаблонну мову: відповіді у великих масштабах створюють пробіли для менших масштабів.
Розробники і заповнювачі проекту можуть бачити ADR, подібно як змінюється склад команди з часом.
Мотивація за попередніми рішеннями є видимою для всіх, теперішніх і майбутніх.
Звіт про досвід
Можливо, ви помітили, що цей допис відформатовано, як сам ADR. Цей формат використовується у декількох наших проектах з початку серпня. Це не дуже довгий час у глобальному розумінні, але ранні відгуки як клієнтів, так і розробників були досить позитивними. За цей час у нас було від шести до десяти розробників, які оберталися за допомогою ADR. Всі вони заявили, що цінують рівень контексту, який вони отримали, читаючи його.
ADR є особливо корисним для досягнення довгострокових намірів. У нас є декілька клієнтів, які стабілізують свої поточні системи, але шукають більшого зворотного втручання у не надто далеке майбутнє.
Потенційним запереченням є те, що утримування цих проектів у керуванні версіями з кодом робить їх менш доступними для менеджерів проектів, змовників клієнтів та інших людей, які не живуть під контролем версій, як це робить команда розробки. На практиці, наші проекти майже всі живуть у приватних сховищах GitHub, тому ми можемо обмінюватися посиланнями на останню версію головного майстра. Оскільки GitHub виконує автоматичну обробку, вони виглядають так само привітними, як і будь- яка сторінка Вікі.
Поки що ARD є корисним інструментом, тому ми продовжуємо ним користуватися.
