Jak analyticky zdokumentovat formuláře se složitou logikou chování?

Nedávno jsme v jedné bratislavské firmě uskutečnili 2-denní workshop, jehož cílem bylo zlepšit postupy prací na analytických dokumentech. Během této konzultace jsme řešili několik zajímavých problémů. Jeden z nich považuji za natolik zajímavý, že jsem se rozhodl o něm napsat tento článek.

Uvedená firma nabízí informační systémy z oblasti pojišťovnictví. Proto není divu, že mnohé formuláře tohoto informačního systému vykazují velmi složitou logiku chování. Produkty pojišťovnictví většinou obsahují spoustu podmínek a větvení podle právě zadávaných údajů. Vývojáři se potýkali nejvíce s tímto analytickým problémem: Jak tyto formuláře vhodně analyticky zdokumentovat?

Provedli jsme nejprve inventuru současného stavu ve firmě. Výchozí stav bylo možné charakterizovat jednoduše slovy „z historických důvodů nemáme žádnou dokumentaci analytické povahy“. To je pro firmu samozřejmě velice nepříjemná situace a to nejenom z důvodu dalšího rozvoje systému, ale i z důvodu údržby. Každý zásah do systému začíná detektivkou „jak to vlastně je, jak se to žádá a co se vlastně bude programovat“. Jakákoliv změna resp. oprava programu představuje obrovskou režii a celý proces změnového řízení se tak stává velmi zdlouhavým.

Vzhledem k tomu, že firma zrovna v té době zahajovala vcelku nový projekt a některé práce na něm byly již vykonány, zaměřili jsme se ve workshopu na tento projekt a snažili se tento problém „složitých obrazovek“ vyřešit přímo v něm.

První dotaz zněl, co je v tomto projektu hotové. Bylo mi sděleno, že mají k dispozici tzv.„návrh obrazovek“. Vývojáři promítli návrh formulářů a na něm se snažili vysvětlit chod zadávání údajů. Z pohledu analytického modelování se v tomto případě vlastně jednalo o popis obrazovek vzniklých z analytického scénáře případu užití s názvem „Založení životního pojištění“.

Po určité chvíli jsme však museli konstatovat, že jsme se ve vysvětlování návrhu obrazovek díky složité logice tak trochu „zamotali“ tím, že jsme takříkajíc „skákali“ z jednoho problému do druhého.

Následující moje rada účastníky workshopu tak trochu překvapila: „Podle mých zkušeností je nejlepší zapsat logiku pomocí jednoduchého slovního scénáře případu užití a to přesně tak, jak se chová program, když běží. Návrh obrazovky v jakékoliv podobě by se měl použít v podstatě pouze jako doprovodný dokument na ukázku konkrétní představy návrhu obrazovky resp. jako pomůcka při vysvětlování chodu scénáře zejména pro laika, který si na rozdíl od vývojáře neumí obrazovku vytvořenou scénářem představit… “

Námitka z jejich strany zazněla: „Ale toho je strašně moc …“

Odpověď: „To je spíš argument pro to, že se to musí napsat, než že by to byl argument proti tomu to psát …“

Další námitka: „Nebude to přehledné.“

Odpověď: „Pokud to napíšete čistě podle přesných a přísných pravidel psaní scénářů případů užití, potom to bude přehledné. Samozřejmě, že je to pro analytika začátečníka z počátku dost obtížné, ale výsledek je překvapivě kvalitní: Přímo na tomto scénáři si ověříte, zda je logika správně, navíc zjistíte, zda nedošlo k chybám, k nechtěnému „posunu meta“ (tj. co je natvrdo, mělo být v hodnotách instancí anebo naopak, o posunu meta viz free kniha Analytické modelování strana 43), resp. zda logice všichni rozumí. Pro laika pak přidáte schematicky namalované obrazovky pro představu, jak by to fungovalo. Mohu vás ujistit, že po určité době analytik začátečník získá praxi a píše scénáře dobře a kvalitně, pokud je k tomu veden.“

V rámci workshopu jsme tedy přistoupili k psaní takového scénáře přímo ve Wordu. Dodržovali jsme přitom pravidla pro psaní scénářů, o nejdůležitějších z nich se zde zmíním (velmi podrobně a prakticky se dané problematice zabýváme například v rámci veřejného školení Efektivní Use Case techniky).

Jaké jsou tedy hlavní „tipy a triky“ (kromě základních pravidel) pro psaní přehledného scénáře?

Nasaďte vzor Exception Flow (alias Happy Scenario). Tento vzor vám oddělí scénáře zpracování mezních stavů (tj. toky výjimek) od hlavního „šťastného to scénáře“, kde vše proběhlo ok (o tomto vzoru viz zmíněná kniha Analytické modelování, strana  114).

Používejte vztah «include» mezi případy užití i tam, kde se nejedná o opětovnou použitelnost, ale navíc nasaďte tento vztah i jako fintu pro zpřehlednění scénáře také tam, kde se nejedná o re-use. Obecně je vztah «include» použitím jednoho případu užití druhým a je obdobou volání mezi funkcemi. Je povinností tento vztah zavést v případě nalezení opětovné použitelnosti (scénáře se pak neopakují). Dá se však použít i pro zpřehlednění scénářů: Zavolání případu užití v určitých bodech výrazně zjednoduší čtení scénáře, protože detaily některého zpracování nejsou v dané chvíli scénáře viditelné a schovají dovnitř volaného případu užití.

Rozlišujte slova „může“ a „musí“. Obsluha má při zadávání údajů v některých případech volnost v tom, zda údaje přidat, zadat apod. V tom případě zvolte formulaci „obsluha může …“, v případě že obsluha musí provést danou sekvenci kroků, slovo „musí“ neuvádějte, protože se tato část scénáře chápe jako implicitně povinná. Pozor však na jeden rozdíl: Pokud je pole tzv. povinné (resp. naopak nepovinné), nejedná se o formulaci „obsluha musí“ (nebo naopak „může“ resp. „nemusí” zadat). Existuje rozdíl mezi nepovinnou hodnotu v poli a formulací „obsluha může…“, druhá formulace ve smyslu „obsluha může“ znamená, že obsluha „může a nemusí“ vstoupit do celé sekce určitého scénáře, oproti tomu označení pole jako „povinné / nepovinné“ vyjadřuje již konkrétní pravidlo pro pole v dané sekci.

V některých případech má obsluha možnost díky formulářové logice zpracování událostí doslova kdykoliv provést určitou sekvenci scénáře. V tom případě tuto větu vložte buď někam na začátek daného scénáře resp. do určité dané pozice ve scénáři, kde je toto zadání ještě možné s úvodními slovy: „Obsluha může kdykoliv …“

Používejte návěští pro označení sekcí scénářů. Osobně nedoporučuji používat číslování odstavců, ale doporučuji raději používat označení částí celých textů pomocí „pseudo-nadpisů“ (obdoba návěští ve strukturovaném programování resp. regionu v některých programovacích prostředích), které se zapíší graficky odlišně od textu samotného děje scénáře. Používám za tím účelem obdobu poznámky v programu, tj. zapisuji návěští jako „dvě lomítka + text nadpisu“ a použiji zelenou barvu fontu. Odvolání se na odstavec přes návěští odstraňuje vážný problém u číslování odstavců při vložení resp. při vymazání odstavce, navíc označení části scénáře nadpisem výrazně zpřehlední scénář významově „o co tam jde“. Mnohdy jsou takovéto části scénářů s nadpisem mapovány přímo na prvky obrazovky. Například část scénáře nadepsaná jako //zadání základních údajů osoby může být realizována ve formuláři pomocí záložky apod.

Malá ukázka scénáře z workshopu:

UC Založení životního pojištění

…předcházející část scénáře…

//zadání další osoby do pojištění Obsluha může zadat další osoby do pojištění: Pokud věk první osoby je věk dítěte, potom lze přidat maximálně další dvě osoby a musí být dospělé. Pokud věk první osoby dospělý, potom lze přidat maximálně dalších 5 osob, děti i dospělí. Pokud je v obou případech další osoba dospělá, tak se zadávají další údaje, viz UC Zadání údajů dospělé osoby.

…pokračování scénáře…

Všimněte si, že scénář nejenže přesně popisuje algoritmus programu, takže lze na základě jeho rozboru velmi dobře zkontrolovat jeho platnost, ale navíc lze posoudit další možnosti změn, například zda se hodí zavést již zmíněný posun meta, například takto:

  • věk dítěte je natvrdo v programu anebo je nastaven v konfiguraci,
  • počty osob v daných podmínkách jsou natvrdo anebo nastaveny v konfiguraci
  • podmínky jsou / nejsou napsány polymorfně (pro účely konfiguračního vložení podmínky do daného místa vyhodnocení)
  • atd.

Uvedené scénáře lze ještě doplnit obrazovkami. K tomu doporučuji vytvořit buď „první nástřel obrazovek“ v daném prostředí (například vytvořený pomocí Visual Studia apod.) anebo použít některý z pomocných nástrojů návrhu obrazovek. Jako vhodný považuji k tomu  účelu například nástroj MockupScreens.

Konec článku

Categories

About the Author:

správce a majitel Serveru objektových technologíí http://www.objects.cz

2 Comments
  1. Martin

    Dobrý den pane Kraval,
    díky za článek. Měl bych doplňující dotaz na metodiku analýzy obrazovek. Jde mi konkrétně o to, kam a jak specifikovat validace prováděné na formulářích (ať už frontendové, např. javascriptem nebo backendové), příp. jak specifikovat datové zdroje, které se mají použít pro inicializaci obrazovek (např. comboboxů). Ve stávající praxi modelujeme obrazovky přímo v EA (což je tedy občas utrpení) a logiku validací se snažíme psát přímo do poznámek jednotlivých elementů – např. že je dané textové pole povinné, že může obsahovat pouze numerické znaky, že musí odpovídat danému regexu, atd. Díky za odpověď.

  2. Díky za váš příspěvek,
    rád odpovím:

    1.
    Opravdu dělat obrazovky v EA hraničí s masochismem a pokud jsem měl tu pravomoc, tak jsem to zakazoval. Umisťovat texty validací do EA je navíc velmi nepraktické z toho důvodu, že jsou pak tyto texty “rozprsknuty” po celém nástroji na drobné kousky a těžko se k nim přistupuje, tj. musí se nejprve daný prvek najít, pak otevřít a pak vstoupit do poznámky. Nedej bože když musíte pracovat najednou s opravou vícero textů v různých prvcích. Obrazovky v EA nebrat…

    2.
    Osobně preferuji čistý text doplněný o obrazovky analytické povahy (tj., pouze jednoduché obdélníčky). Text má tu výhodu, že autor vede čtenáře tam, jak třeba. Text však musí být napsán přehledně.

    3.
    Co se týče povinných kontrol, doporučuji umístit je do závorky hned za slova “obsluha zadá X”. Závorka označí možnost příležitostně tento text přeskočit. Pokud jsou podmínky příliš dlouhé, dejte tento text mimo hlavní text a odkažte se na něj v dané závorce (např. “validace viz…” apod.).
    Poznámka: Musíte ve firmě používat jednotnou syntaxi pro tyto kontroly, pokud jsou složitější, tak ve firmě musí existovat dokument, který tato pravidla psaní kontrol zavádí.

    4.
    Vyplnění comboboxů apod. analytik nepopisuje přímo s těmito prvky, ale použije analytickou formulaci pomocí vzoru: “Obsluze se zobrazí seznam něčeho (co z toho)”.
    Víc už analytik nepopisuje, protože jaký to bude prvek v designu rozhoduje expert na obrazovky daného prostředí. Pokud budoucí uživatel chce vidět obrazovku “už teď”, doplní se tento text o přiložený “nástřel obrazovky” v daném prostředí s již konkrétními prvky.

    Doufám, že odpověď pomohla.

0 Pings & Trackbacks

Leave a Reply to Martin Cancel reply