Передумови: Мої співробітники та я пишемо статтю для академічного журналу. У ході наших досліджень ми написали програму моделювання на Java. Ми хочемо зробити програму моделювання вільно доступною для використання іншими. Ми вирішили розмістити код у сховищі GitHub. Щоб полегшити користування іншим, ми хочемо написати гарну документацію для нашої програми, зокрема:

• Javadocs для кожного класу та методу
• Як користуватися кодом
• Опис структури високого рівня коду

Моє запитання на високому рівні: Ви можете надати хороший приклад слів та діаграм, які можна використовувати для опису структури програми на високому рівні? Сюди входить як підпитання:

1. Як ми показуємо, які класи містяться в яких пакетах?
2. Як ми показуємо, які пакунки залежать від інших пакетів?
3. Як ми показуємо, як об’єкти / класи в програмі працюють разом?
4. Ми намагалися використовувати принципи дизайну, керовані доменом, при розробці мого коду. Як ми можемо показати відповідність між об'єктами домену та певними файлами вихідного коду, що кодують ці об’єкти? (Дивіться опис проекту "всюдисуща мова" нижче.)

Що я зробив досі

Всюдисуща мова

Ми поміщаємо опис коду "всюдисущою мовою" ubiquitous-language.md, вміст якого нижче.

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

У кожному періоді відбуваються такі події:

1. Якщо вантаж повинен прибути на об'єкт в поточному періоді, то рівень запасів об'єкта збільшується на X одиниць.
2. Якщо графік показує , що поточний період є звітним періодом, то об'єкт являє звіт до постачальнику . Постачальник може отримати звіт негайно, або із затримкою в кілька тижнів, як зазначено в розкладі .
3. Якщо постачальник отримав звіт , то на основі політики поповнення він обчислить кількість поповнення X одиниць. Планується, що відправлення X одиниць товару буде заплановано після закінчення строків l.
4. Клієнти прибувають на об'єкт і вимагають X одиниць товару. Будь-який незадоволений попит втрачається.

Структура вихідного коду

Ми розміщуємо неповний "високий рівень" опису коду у файлі structure.md, вміст якого нижче.

Структура рівня упаковки

На найвищому рівні вихідний код організований у три пакети

• com.gly.sfs Основний клас з mainметодом знаходиться в цьому пакеті.
• com.gly.sfs.model Класи доменних моделей містяться в цьому пакеті.
• com.gly.sfs.util Класи помічників знаходяться в цьому пакеті.

Зазвичай ви використовуєте UML для описаної вами мети. UML в основному розпадається на два типи діаграм: структурну та поведінкову.

Структурні діаграми включають: склад, розгортання, пакет, клас, об’єкт та компонент. Діаграми поведінки включають: послідовність, стан машини, зв’язок, випадок використання, огляд та огляд взаємодії.

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

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

http://omarfrancisco.com/wp-content/uploads/2011/07/sequencediagram.png

Я ніколи раніше в житті не бачив цієї діаграми, але я можу розповісти про цю систему ряд речей. Є чотири основні компоненти (іменники у вашій системі - як правило, класи): Перегляд, Контролер, Даний проксі та Постачальник даних. Стрілки - це "поведінка" або виклики методу. Діаграма послідовностей в основному хороша для показу однієї важливої ​​взаємодії між купою компонентів. У вас є одна діаграма послідовностей для кожного важливого потоку через вашу систему. Я можу сказати з цієї конкретної діаграми, що "Контролер" відкриває метод під назвою "phoneIsComplete ()", який, в свою чергу, залежить від методу "lookupPhone ()" DataProviderProxy, який, в свою чергу, залежить від методу "lookupPhone ()" DataProvider.

Тепер ви можете стогнати і подумати, що "uggg ... це не дає мені великої картини системи - це лише індивідуальні взаємодії через систему". Залежно від складності системи, це може бути серйозною проблемою (прості системи, безумовно, можуть обійтись лише колекцією діаграм послідовності). Отже, переходимо до структурних діаграм і дивимось на щось на зразок статичної діаграми класів:

http://www.f5systems.in/apnashoppe/education//img/chapters/uml_class_diagram.jpg

Діаграми класів допомагають нам з’ясувати дві важливі речі: кардинальність та типи відносин класів. Заняття можуть бути пов’язані між собою різними способами: об'єднання, агрегація та склад. Технічно кажучи, існує різниця між "статичними відносинами класу" та "відносинами екземплярів". Однак на практиці ви бачите ці рядки розмитими. Основна відмінність полягає в тому, що відносини статичного класу зазвичай не включають в себе кардинальність. Давайте подивимось на приклад вище та побачимо, що ми можемо бачити. По-перше, ми можемо побачити, що "Особливий порядок" та "Звичайний порядок" є підтипами "Наказів" (спадкування). Також ми можемо побачити, що один Клієнт має N замовлень (це можуть бути "Звичайні замовлення", "Замовлення" або "Спеціальні замовлення") - об'єкт Замовника не відповідає " я справді не знаю. Ми також можемо побачити ряд методів (у нижній половині кожного поля класу) та властивості (верхня половина кожного поля класу).

Я міг довго говорити про діаграми UML, але це основи. Сподіваємось, це допомагає.

TLDR; Виберіть одну поведінкову та одну структурну UML-діаграму, навчіться її створювати, і ви зробите те, що намагаєтесь досягти.

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

A picture is worth a thousand words.

Те, як ви малюєте картинку про код, - це навести приклади коду. Багато їх. Так ви створюєте нового клієнта (код). Так ви обробляєте замовлення (код). Це не тільки дає споживачеві вашого коду місце для початку, але ілюструє, як усі об’єкти з'єднуються між собою та взаємодіють. Якби я використовував ваш код, найбільша прихильність, яку ви могли мені зробити, - це надати багато зразків коду.

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

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

Я вважаю https://www.websequencediagrams.com/ надзвичайно корисним інструментом для опису взаємодії між компонентами в програмі або між службами в розподіленій програмі. Це просто полегшує процес створення та підтримки діаграм послідовностей UML.

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

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