Pojmenovávání a dokumentace - 8. díl

Tohle bude jedna z těch otravnějších kapitol, ovšem důležitá. Půjde o pojmenovávání a dokumentaci. Je extrémně důležité vést k celému projektu dokumentaci, správně pojmenovávat a dobře komunikovat. Ne vždy se tato aktivita setkává s pochopením, ale je nesmírně důležitá. Lidé si na to časem zvyknou a ve finále je daleko lepší provoz, někdy dokonce i levnější. Jak už komentovat kód, tak stejným stylem pojmenovávat objekty, používat jednotný code style. Uvedu tu několik dobrých principů, kterých se držet, aby Vám práce šla lépe.

Pojmenovávání databázových struktur

Jistě jste si všimli, že v ukázkách kódu se držím určitých vzorců pojmenovávání. Můžete si je zvolit po svém. Takováto pravidla by se měla objevit v dokumentaci dostupné všem uživatelům. Já používám tyto:

Označení	Popis
DIM_*	Dimenze
FACT_*	Faktová tabulka
VIEW_*	View
STG_*	Stage table (v jakékoliv vrstvě) – tabulka, která se vytvořila primárně z důvodu optimalizace nebo k zajištění skrytého mechanismu
*_HIST	Tabulka s historickými daty – používá historizační pattern. Původně z existující tabulky, ze které denně ukládá data v rozmezí OD – DO
BACKUP_*	Tabulka se zálohou, typicky ve schématu bck
*_yyyymmdd	Datum v postfixu typicky u tabulky se zálohou určuje ze kterého dne je záloha

Pojmenovávání databázových struktur

Další důležitou věcí je pojmenovávání sloupců. Někdo to dělá všude, ale já to dělám jen u nejednoznačných případů a sloupců nesoucích nějakou typickou informaci. U sloupců, kde není jasný rozdíl mezi dalším sloupcem, je vhodné uvést prefix. Prefixem může být název tabulky nebo něco jiného co jasně identifikuje o jaký atribut jde. Dejme tomu, že mám sloupec type. No a dál nevím, je to customer type, material type nebo phone type? Takže prostě to do uvedeného sloupce napíšu. Problémová bývají slova: type, state, status, district, country, name, phone, address, contact a mnoho dalších.

Dobrou praxí je také u některých sloupců přidávat prefixy. Například u počtů, příznaků a kategorií. U počtu přidávám prefix CNT_* a u příznaků FLAG_*, u kategorií CAT_* a hned vím jaké mám očekávat hodnoty uvnitř sloupce. Pokud pracujete s nějakým KPI, kde máte cíl a aktuální hodnotu, je vhodné pojmenovávat také konzistentně. Například ACT_*, TARG_*. Vhodné je také v tabulce uvádět cíl až za aktuálem – hned vím, že procenta se vypočtou ACT / TARG. Ať už se rozhodnete pro jakékoliv názvy je důležité je držet konzistentní napříč celým systémem.

Komunikace

S problémovými slovy souvisí, ale i to co moc neovlivníte, a to že lidé mimo Váš tým si to prostě budou plést. A je velmi důležité dbát na správnou komunikaci – ta je jednou z nejdůležitějších, protože nic nedokáže způsobit více problémů než špatná komunikace. Nechcete trávit čas nad stále stejným problémem a stále dokola upravovat řešení, protože jste si se zadavatelem nerozuměli. Když si dáváte pozor, toto lze poměrně docela dobře odbourat. Existuje bohužel případ, se kterým nic neuděláte a to je, když zadavatel neví co chce. Pak to stejně budete 10x upravovat než si rozmyslí co potřebuje vidět. Jediná rada, kterou Vám dám je obrnit se trpělivostí. Čím více budete znát business, ve kterém se pohybujete bude takových případů ubývat, protože už budete myslet za ostatní kolegy dopředu. Ale nikdy se těchto problému zcela nezbavíte (fluktuace pracovních míst, noví zadavatelé, ne tak chytří kolegové).

Dokumentace

Je jedno jakým způsobem dokumentaci vedete (ideálně automatizovaným), ale je potřeba ji vést. Důležitý je lineage kódu. Jak na sebe navazují jednotlivé joby a loady. Většinou stačí prolinkování, pokud byste potřebovali něco komplexnějšího existují na to nástroje typu Manta (dost drahé). Kromě dokumnetace databázových stuktur, ale generujete i reporty a ty je potřeba do dokumentace také zahrnout. Minimálně to, kde jsou uložené, jaký používají zdroj dat, kdo je za něj zodpovědný atd.

V kódu je také důležité napříč týmem používat stejný code style (jaký je samozřejmě na Vás).

Ještě znovu zmíním externí tabulky, u kterých je dokumentace nesmírně důležitá, hlavně zodpovědná osoba.

Sada testů 5-minut

Jak poznat jestli mám správnou dokumentaci? Výbornou odpovědí je sada testů 5-minut. Pokud některý z následujících úkolů přesáhne 5 minut, je vaše dokumentace nedostatečná. Ve výčtu níže používám slovo funkcionalita, obecně si místo ní představte report, databázovou tabulku, view.

5 minut – získejte výčet všech Vašich funkcionalit
5 minut – získat jméno člověka, se kterým mohu konkrétní funkcionalitu projednávat a zajistit změnu. Osobně doporučuji 2 osoby – zhotovitele (ten co rozumí reportu a bude ho upravovat) a business vlastníka (ten rozumí reportu z pohledu businessu).
5 minut – získat popis funkcionality
5 minut – dohledat všechny situace, kde je funkcionalita použita (extrémně důležité, ale těžko proveditelné). Nejzazší způsob je to prostě vypnout a počkat si až někdo bude reklamovat, že to nefunguje. Bohužel bývá také často jediným způsobem jak tuto informaci získat (rozhodně přesáhne 5 minut :-).

RACI

Co se týče druhého bodu testů 5-minut existují komplexnější způsoby jak toto sledovat. O jejich použití si musíte rozhodnout sami – někdy mohou být trochu overkill pro určité projekty. Jedním z těchto způsobů je RACI (také lze dohledat pod pojmem RAM = Responsibility Assignment Matrix). Jednoduše do matice k reportům zapíšete osoby.

R = Responsible – odpovědná osoba
A = Accountable – zastřešující osoba, určuje směr
C = Consulted – spolupracovníci
I = Informed – neaktivní účast, nutné informovat

Shrnutí

Je potřeba důkladně vést dokumentaci.

Raději ještě jednou. Je potřeba důkladně vést dokumentaci.

Pojmenovávejte smysluplně datové struktury a sloupce, používejte prefixy a postfixy. Správně komunikujte. Udržujte lineage kódu, používejte jednotný code style, dokumentujte co nejvíc automatizovaně.

Sada testů 5-minut je dobrý způsob jak zjistit, že mám dokumentaci v pořádku. S druhým testem může pomoci matice RACI, kde k funkcionalitám do tabulky zapisuji důležité osoby.