Písemný referát pro seminář Praktikum z programování.
Ondřej Bojar
...lidé často znovu vymýšlejí věci, které už někdo popsal...
...někdy jen proto, že cizí popisy myšlenek nevyhovují (jsou příliš obecné nebo naopak příliš konkréntní, příliš nesrozumitelné, vyžadují příliš mnoho dalších znalostí ap.)...
...psaním i čtením odborných popisů tráví lidé hodně času - chtějme tento čas zkrátit...
Vzorce jsou takové odborné dokumenty, jež usnadní autorovi psaní a čtenáři pochopení sdělovaných myšlenek.
Tento referát pojednává o specifickém stylu odborných dokumentů, tzv. vzorcích (patterns). Vzorcem je do určité míry formalizovaný psaný dokument, který v sobě přináší popis častého problému v určitém kontextu nějakého oboru spolu s osvědčeným řešením. Příklady vzorců naleznete v dalším textu.
Referát je určen všem, kteří občas potřebují předat nějaké své zkušenosti a chtějí to učinit způsobem co nejefektivnějším. Forma vzorce je navržena tak, aby byl záznam myšlenek pro autora co nejpohodlnějsí a aby pochopení vzorce bylo pro čtenáře co nejrychlejší a nejsnadnější. Jelikož jsou vzorce poměrně novým způsobem záznamu myšlenek, je jejich forma stále vylepšována a styl jejich psaní se autor od autora liší. Cílem tohoto referátu je představit vám podrobněji jeden styl, který se mně osobně zdá velmi účinný, v příkladech dalších vzorců můžete posoudit styly jiné.
Čím se vzorce liší od obyčejného popisu problému a jeho řešení? Co přinášejí nového?
Dobrý vzorec již v rámci svých Povinných sekcí představuje čtenáři nejen problém a jeho řešení, ale především kontext, v němž bylo řešení navrženo a zvoleno. O důvodech volby daného řešení se čtenář explicitně dozví prostřednictvím Viditelných sil, jež autora řešení ovlivnily. Čtenář tak velmi záhy a snadno najde odpověď na své první otázky: K čemu je to celé dobré? Proč to vypadá právě takto?
Až čtenář (pouhým nahlédnutím do vzorce) zjistí, že ho problém a navrhované řešení zajímá, bude se více zajímat o aspekty zvoleného řešení. Odpovědi na své otázky najde v Rozšiřujících sekcích vzorce. Často se jedná o příklady užití vzorce v praxi, v případě vzorců týkajících se programování může jít o zdrojové texty programů jako ukázka implementace myšlenky vzorce v nějakém konkrétním programovacím jazyce ap.
Velmi podstatnou kvalitou, kterou by vzorce měly vykazovat, je Čitelnost na první pokus. Čtenáři vaše řešení nebudou ani studovat, bude-li to vyžadovat přílišné úsilí hned z počátku. V tomto referátu se dozvíte řadu doporučení, jak vzorce udělat snadno čitelné, s Přeskočitelnými sekcemi a podobně. Při psaní vzorců je ale nutné zároveň zajistit celkovou provázanost vzorce, nepokazit přílišným rozčleněním textu jeho spojitost a plynulost čtení. Vhodného kompromisu lze dosáhnout rozdělením složitého řešení do Souboru vzorců a zajištěním dobré návaznosti mezi příbuznými vzorci.
V tomto textu najdete kromě řady pravidel pro psaní dobrých vzorců i celou řadu příkladů, abyste se mohli nechat inspirovat. Vlastně celý referát je zapsán formou souboru vzorců, po vzoru stránky A Pattern Language for Pattern Writing, z níž do značné míry čerpá. Anglicky mluvící čtenáři na zmíněné stránce naleznou soubor vzorců pro psaní vzorců zároveň napsaný formou vzorců. Jak praví její abstrakt, stránka se snaží shrnout nejlepší dovednosti pro psaní vzorců a zároveň je demonstrovat na dobrém příkladu, stránka sama chce být fungujícím příkladem. Dlužno říci, že je.
Nedílnou částí tohoto referátu budou i odkazy na sbírky hotových vzorců, určených zejména pro obor informatiky a programování.
Není mi známo, že by existoval český dokument pojednávající o vzorcích. Z tohoto důvodu jsem sám musel zavést český překlad vzorec termínu pattern.
Čtěte tento referát tak, jak lze číst vzorec každý: hledáte-li odpověď na konkrétní problém, projděte si přiložené tabulky problémů a řešení, až najdete vzorec, který nejspíše na váš problém odpovídá, začněte čtením sekcí jméno, problém a řešení, ostatní sekce jsou Přeskočitelné. Až zjistíte, že vás vzorec patrně zajímá, přečtěte si oddíly kontext a síly, abyste zjistili, jestli je vzorec použitelný ve vaší situaci. Závěrem se podívejte na princip, výsledný kontext nebo příbuzné vzorce a příklady.
Jinou možností je číst celý referát pěkně popořádku, forma vzorce je totiž navržena tak, aby proud čtenářových myšlenek netrhala.
V tomto textu jsou kurzívně vyznačována jména vzorců, tučně pak jejich vnitřní sekce. Přímé hypertextové odkazy na vzorce (způsobující typicky modré a podtržené písmo) jsou záměrně potlačeny, aby nerušily ve čtení. Chcete-li, můžete užít rejstříku na úplném konci tohoto dokumentu.
Referát byl pro přehlednost rozdělen do následujících kapitol:
Věřím, že vás forma vzorce zaujme, a že se rovněž pokusíte zapisovat své dovednosti tímto čitelným způsobem.
Jste zkušený odborník ve svém oboru. Postřehl jste, že opakovaně užíváte určité řešení častého problému. Rád byste se o své zkušenosti podělil s ostatními.
Jak popsat opakující se řešení určitého problému tak, aby bylo snadno použitelné i pro ostatní?
Napište své řešení formou vzorce (pattern). Zachyťte obojí, problém i jeho řešení, současně zdůvodněte, proč je řešení použitelné. Užijte všechny Povinné sekce, abyste zajistili jasné sdělení všech základních informací. Přidejte Rozšiřující sekce s dalšími užitečnými informacemi. Rozšiřte vzorec mezi nejširší publikum, které by jej mohlo využít, aniž by tím byla ohrožena vaše výhoda ve veřejné soutěži. Často to znamená uveřejnění vašeho vzorce výhradně pro interní potřeby vaší společnosti.
Pokoušíte se formou vzorce popsat rozsáhlou proceduru nebo složité řešení složitého problému. Některé z popisovaných kroků je třeba uplatnit jen za určitých okolností. Jednotlivé části problému mohou mít podle okolností alternativní řešení. Jeden vzorec neobsáhne celou složitost problému.
Jak přehledně popsat řešení, aby bylo současně možné používat jeho různé části za různých okolností?
Rozdělte rozsáhlý problém a jeho velké řešení nebo postup na dílčí problémy a odpovídající řešení. Popište zvlášť každou dvojici problém/řešení v samostatném vzorci, jako součást souboru vzorců. Každý vzorec by měl řešit jeden specifický problém. Usilujte o to, aby bylo vzorec možné smysluplně použít i samostatně nebo jen s omezeným počtem dalších vzorců vašeho souboru.
Aby dílčí vzorec získal svou identitu, dejte mu Návodné jméno, jímž se na něj bude možné později odkazovat. Pak popište celkový problém a způsob, jakým na sebe dílčí vzorce navazují, ve Shrnutí souboru vzorců. Jednotlivé vzorce mezi sebou propojte pomocí Čitelných odkazů na vzorce, především v sekcích Kontext a Příbuzné vzorce.
Soubor vzorců by měl být uveden Shrnutím souboru, které popisuje celkový problém a vzorce, jež jej řeší. Shrnutí typu Problém/Řešení je klíčovou částí tohoto úvodu, protože dovoluje vyjímat jednotlivé vzorce ze souboru, zvláště pokud se k materiálu jen odkazujeme. Větší soubory vzorců mají často netriviální strukturu, kterou lze nejlépe zvýraznit užíváním Titulků rozlišujících strukturu. Pokud má jeden problém více alternativních nebo dokonce navzájem se vylučujících řešení, můžete jejich popisy uvést v samostatných vzorcích. V tomto případě pro čtenáře Zvýrazněte společný problém této skupiny vzorců.
Dobrým způsobem, jak propojit vzorce v souboru a jak ujasnit použití souboru vzorců v praxi, je Fungující příklad, který ilustruje použití vzorců na příladu většího problému.
Vzorce popisující tvorbu souboru vzorců přesahují rozsah tohoto referátu, a naleznete je proto jen v podobě náčrtků v kapitole 6.
Samotný tento referát je příkladem souboru vzorců o tom, jak psát vzorce. Představuje řešení jako soubor vzorců, z nichž každý popisuje konkrétní menší problém a jeho řešení.
Vzorec je popis řešení určitého problému, který se opakuje v určitém kontextu. Této charakteristice však zdánlivě vyhovuje mnoho typů psaných dokumentů. Hlavní výhodou formy vzorce je však schopnost popsat kromě samotného řešení především důvody jeho užívání. Klíčem k tomuto popisu je charakterictiská struktura formy vzorce.
Vzorce v tomto oddílu popisují vnitřní strukturu každého vzorce, ať už je samostatný, nebo součástí Souboru vzorců. Vzorce jsou srozumitelnější, jestliže obsahují všechny Povinné sekce. Rozšiřující sekce dávají autorům vzorců dostatečnou možnost podle potřeby přidat další informace a rozčlenit je co nejpřehledněji.
Jak se ujistit, že všechny potřebné informace jsou ve vzorci obsaženy?
Píšete vzorec, ať již samostatný, nebo jakou součást většího souboru vzorců.
Čtenáři očekávají, že ve vzorci naleznou určitou informaci. To je to, co odlišuje vzorce od pouhých popisů problémů a řešení.
Zajistěte, aby ve vaše vzorci nechyběla žádná z následujících povinných sekcí. Přesná jména sekcí se v různých stylech psaní a podle oboru použití vzorců různí a pořadí uvedených sekcí není tak důležité, jako skutečnost, že žádná z nich nebyla vynechána. Zvolíte-li jeden styl formy vzorce, snažte se jej dodržet i později.
Pokud váš text vybízí k podrobnějšímu strukturování základních sekcí svou přílišnou složitostí nebo délkou, zvažte, zda jej nelze raději srozumitelně rozčlenit do Souboru vzorců.
Cílem vzorce je obsáhnout nejen popis řešení určitého problému, ale poskytnout čtenáři i průhled do úvah, které předcházely volbě řešení. Povinné sekce vzorce zajišťují, aby byly všechny základní informace předány. V mnoha vzorcích, které byly napsány od prvního vydání knih The Timeless Way of Building [Alexander79] a A Pattern Language [Alexander77], se ukazuje, že tyto Povinné sekce představují minimální soubor informací potřebný ke sdělení určitého vzorce.
Všechny vzorce v tomto souboru obsahují Povinné sekce. Tím je zaručeno, že potenciální uživatelé vzorců pochopí, kdy a proč vzorce použít. Sekce vzorců jsou zvýrazněny písmem. Většina vzorců tohoto souboru začítá sekcí problém následovanou popisem kontextu, někdy je tomu naopak.
V různých stylech psaní vzorců se můžete setkat s odlišnými názvy a uspořádáním sekcí. Přehled různých stylů spolu s popisem jejich vlastností lze najít v [Copelien96], v páté kapitole tohoto referátu jsou na příkladech vzorců pro programátory některé odlišné styly vzorců ilustrovány.
Christopher Alexander v knize A Pattern Language užívá tento základní postup: Povinné sekce jsou odděleny typograficky, odstavce řešení začínají slovem "therefore" (a proto). V knize Design Patterns [GHJV95] jsou sekce problém a řešení nahrazeny oddíly záměr a použitelnost a doplněny konkrétnějším příkladem problému v sekci motivace. Sekce řešení je rozvedena ve čtyčech oddílech: struktura, účastníci, spolupráce a implementace.
Píšete vzorec se všemi Povinnými sekcemi, abyste zaručili, že jsou ve vzorci obsaženy všechny nezbytné informace.
Jak sdělit důležité informace, které se však nehodí do povinných sekcí?
Následující sekce lze do vzorce přidat, pokud to usnadní porozumění vzorci nebo zlepší propojení vzorce s příbuznými vzorci.
Podle potřeb vašeho oboru lze samozřejmě zavést i další rozšiřující sekce.
V knize Design Patterns je výsledný kontext znám jako důsledky. Příklady lze nalézt v sekci Známá použití a celý problém je představen na konkrétním příkladu v sekci motivace.
Myšlenku předzvěsti zavedl [Cockburn96], který tuto sekci nazývá symptomy. V lékařských popisech onemocnění je tato sekce klíčová.
Vzorec představuje řešení určitého problému v nějakém kontextu. Jak zajistit, aby čtenář pochopil, proč bylo zvoleno právě popisované řešení?
Píšete vzorec nebo soubor vzorců, která má čtenáři přinést jedno určité nebo více možných řešení nějakého problému. Snažít se ve vzorci užít všechny Povinné sekce a v tuto chvíli chcete psát sekci síly.
Nehledě na zvolený styl vzorce zajistěte, aby síly byly jasně viditelné. Zdůvodnění, proč řešení vzorce použít je jednou z klíčových kvalit vzorce.
Síly můžete zvýraznit buď pomocí odděleného seznamu nebo zavedením smysluplných "jmen" pro každou sílu. V případě vzorců psaných v podobě souvislého textu užijte zvýraznění pomocí písem, podtržení nebo dalších typografických technik.
Tento soubor vzorců užívá pro zápis sil samostatné sekce s vlastním titulkem.
[Foote96] zvýrazňuje síly přímo v souvislém textu popisujícím vzorec.
Vzorec je užitečný, jen pokud je přijat svými čtenáři. Autor vzorce může vynaložit velké úsilí, aby popsal své řešení, všechno toto úsilí však přijde vniveč, pokud čtenář vzorci neporozumí nebo frustrován čtení vzdá. Klíčovou roli pro srozumitelnost vzorce hraje kvalita stylu psaní, tento faktor zde ale nebudeme studovat. V následujících vzorcích popíšeme jiné faktory, některé spíše obecné, některé specifické pro formu vzorce. Uvedené vzorce popisují jevy, jež mají významný vliv na to, jak snadno bude vzorec pochopen.
Vzorce v tomto oddílu jsou použitelné při psaní všech sekcí vzorce nebo souboru vzorců. Jejich cílem je pomoci autorům předat své myšlenky čtenářům vzorců co nejúčinnějším způsobem. Klíčovým krokem je určení Cíleného publika. To pomůže autorům volit Terminologii na míru čtenářů a též Srozumitelné zápisy pro diagramy a ilustrace. Jsou-li mezi čtenáři i programátoři, je na místě přidat Ukázky zdrojových kódů. Zdrojové kódy jako bonus mají navíc výhodu, že je čtenář nemusí číst a pochopit, aby porozuměl celému vzorci.
Při členění svého vzorce usilujte o Čitelnost na první pokus, aby váš čtenář netrpěl tím, že vzorci nerozumí. Mezi osvědčené techniky patří psaní Přeskočitelných sekcí, aby bylo čtenáři hned při prvním čtení jasné, k čemu vzorec slouží, aniž by ho musel celý pochopit.
Váš vzorec může číst mnoho lidí. Jak zajistíte, aby byl vzorec snadno srozumitelný pro zamýšlené publikum?
Píšete vzorec nebo soubor vzorců.
Jasně určete cílené publikum, skupinu lidí, jimž chcete své řešení sdělit. Mějte toto publikum na paměti při psaní svého vzorce. Hotový vzorec můžete na nějakém zástupci cíleného publika "otestovat".
Často je užitečné v úvodu vzorce cílené publikum explicitně popsat. Pomůže to případným čtenářům hned na počátku zjistit, zda je vzorec určen právě pro ně. Může to rovněž pomoci určit význam nejednoznačných výrazů v textu, nejsou-li zavedeny v textu nebo popsány v Rejstříku termínů.
Jasné cílené publikum pomáhá zpřesnit vzorec, neboť představuje kritérium pro rozlišení, které informace do vzorce přidat a které vypustit.
Máte-li Jasné cílené publikum, můžete užívat Terminologii na míru čtenářů.
V tomto souboru vzorců je cílené publikum uvedeno hned v druhém odstavci úvodu.
Jak maximálně zvýšit pravděpodobnost, že čtenář vašemu vzorci správně porozumí?
Píšete vzorec nebo soubor vzorců a máte určeno Jasné cílené publikum.
Používejte terminologii na míru čtenářům. Používejte jen takové termíny, jimž typický člen publika pohodlně bez problémů porozumí. Ověřte si srozumitelnost terminologie na zástupci cíleného publika. V úvodu vzorce nezapomeňte uvést odkaz na zdroj užívaných termínů.
Abyste zajistili, že zbytečně neomezujete případné publikum, užívejte co nejjednodušší jazyk, jímž můžete efektivně předat myšlenky. Přiložte rejstřík méně obvyklých termínů. Nové termíny vysvětlete v poznámkách pod čarou (nebo čtenáře odkažte na Rejstřík termínů).
Vzorec nebo soubor vzorců nemusí být dost dobře srozumitelný čtenářům mimo cílené publikum, je-li terminologie příliš specializovaná.
Vzorec, který je srozumitelný pro cílené publikum, bude spíš užitečný.
Tento vzorec použivá terminologii běžnou pro autory vzorců. Nevysvětluje termíny jako Síly, Kontext, protože cílené publikum je s jejich významem seznámeno a podrobné definice by mu byly spíše na obtíž.
Píšete vzorec a pokoušíte se nějakou část myšlenky sdělit pomocí diagramu nebo ilustrace. Máte Jasné cílené publikum.
Jak zajistit, aby byly diagramy snadno pochopitelné pro celé vaše cílené publikum?
Užívejte v diagramech takové formy zápisu, které jsou pro cílené publikum pravděpodobně srozumitelné. Takové notace by měly být široce užívané a snadno pochopitelné. Pokud používáte standardní notaci, uvádějte vždy odkaz na příslušný standard. Pokud je naopak nebezpečí, že čtenáři váš nestandardní zápis nepochopí, přidejte jasný a stručný popis své notace v místě prvního použití nebo podrobněji v dodatku.
Čím známější notaci užíváte, tím spíše čtenáři vaše diagramy pochopí i bez dodatečného (a rušivého) vysvětlení. Stručná vysvětlení méně obvyklých notací pomohou neznalým čtenářům porozumět vašim diagramům, v lepším případě aniž by je příliš odtahovala od jádra vašeho vzorce. Odkazy na standarní formy zápisu představují pro zvídavé čtenáře cestu, jak se dozvědět více.
Pokud je vysvětlení notace součástí vašeho vzorce nebo souboru vzorců, zajistěte, aby bylo uvedeno v Přeskočitelné sekci.
Člověk hledající řešení nějakého problému často potřebuje prostudovat celou řadu možných řešení. Jak pomůžete čtenáři vašeho vzorce, aby vzorci porozuměl v co nejkratším čase a usnadnil si tak hledání vhodného řešení?
Píšete vzorec se všemi Povinnými sekcemi.
Dosáhnout Čitelnosti na první pokus je velmi obtížný úkol, který by si pravděpodobně zasloužil samostatný soubor vzorců. Přesto lze uvést alespoň několik technik, jež mohou napomoci k vytvoření vzorce čitelného na první pokus.
Abyste se čtenáři vašeho vzorce dozvědět vše co potřebují v co nejkratším čase, musíte jim pomoci číst jen sekce, které potřebují, a jen jedenkrát. Přeskočitelné sekce a Nalezitelné sekce pomohou čtenářům najít sekce, které potřebují. Techniky popsané výše omezují nutnost se při čtení vracet (nebo nahlížet dopředu) a číst sekci vícekrát.
Píšete vzorec, který má být součástí většího celku a k němuž se bude odkazovat. Váš vzorec má všechny Povinné sekce a potřebné Rozšiřující sekce. Usilujete o vzorec snadno srozumitelný, Čitelný na první pokus.
Jak čtenářům zjednodušit pochopení podstaty vzorce a přitom ve vzorci poskytnout dostatek informací nutných pro použití vzorce?
Jasně vyznačte oddíly Problém, Kontext a Řešení, aby čtenář mohl rychle rozhodnout, jestli je pro něj vzorec použitelný. Podrobnější informace (například síly nebo ukázky zdrojových kódů) přidejte v jasně odlišených sekcích, které může čtenář přeskočit, pokud se nezajímá o detaily.
Čtenář, který se snaží seznámit se s větším počtem vzorců, chce velmi rychle provést základní výběr. Příliš mnoho informací je mu zpočátku na obtíž. Většina informací uvedených ve vzorci je potřebná až v případě, že jste se rozhodli vzorec použít (nebo vybíráte už z velmi omezeného počtu vzorců). Tento vzorec představuje způsob, jak popsat podstatu vašeho vzorce bez zabíhání do zbytečných podrobností, a tedy usnadňuje čtenáři rychlý výběr vhodného vzorce.
Nejsou-li Přeskočitelné sekce uvedeny až na konci dokumentu, může čtenář potřebovat hledat ve vzorci další sekci, která ho zajímá. Usnadněte mu to pomocí Nalezitelných sekcí.
Vzorec Ukázky zdrojových kódů jako bonus představuje speciální případ přeskočitelných sekcí. Vzorec Rozšiřující sekce radí, kdy uvést ve vzorci nějakou sekci, kdežto vzorec Přeskočitelné sekce se snaží umožnit čtenáři efektivnější čtení.
"Alexandrijský" styl vzorce používá odlišná písma a znak *** pro oddělení odstavců, aby čtenář mohl snadno nalézt problém a navrhované řešení. Strukturovanější styly vzorců (např. styl tohoto souboru) užívají titulky pro oddělení jednotlivých sekcí. V úvodu k tomuto souboru vzorců je vysvětleno, kterých sekcí si má čtenář všímat pro "rychlé čtení".
V knize Design Patterns [GHJV95] mají vzorce sekci Použitelnost (Applicability), která umožňuje celý zbytek vzorce přeskočit, pokud dosud hledáme řešení určitého problému.
Píšete vzorec v rámci většího celku a hodláte se k němu odkazovat. Váš vzorec obsahuje všechny Povinné sekce a potřebné Rozšiřující sekce, pro snazší čtení jsou některé sekce Přeskočitelné. Usilujete o vzorec snadno srozumitelný, Čitelný na první pokus a použitelný jako referenční materiál.
Jak usnadnit nalezení klíčových prvků vzorce, především sekcí Problém, Kontext, Síly a Řešení?
S ohledem na styl vašeho vzorce zvažte, které sekce čtenář potřebuje při vyhledávání, pokud se ke vzorci odkazuje. Začátky těchto sekcí výrazně označte, aby je čtenář snadno našel. Můžete to udělat použitím titulků, typograficky (použitím písem, podtržení ap.) nebo graficky (vložením diagramů, grafických prvků, hvězdiček mezi sekce).
Počátek vzorce je speciální případ Nalezitelné sekce. Pro usnadnění nalezení počátku vzorce lze užít stínované titulky, návodné ilustrace (tj. zavedené grafické symboly nebo obrázky) nebo začínat každý vzorec na nové stránce.
Sekce nemůže být považována za dobře přeskočitelnou, pokud následující podstatnou sekci nelze nalézt bez čtení nebo pročítání přeskakované sekce. Čím jsou hranice sekcí výraznější, tím snadněji lze sekce přeskakovat.
Přeskočitelné sekce pomohou čtenáři číst vzorec efektivně, tento vzorec pak zlepšuje použitelnost vzorce jako referenčního materiálu, materiálu, k němuž se odkazujeme.
"Alexandrijský" styl vzorce používá odlišná písma a znak *** pro oddělení odstavců, aby čtenář mohl snadno nalézt problém a navrhované řešení. Strukturovanější styly vzorců (např. styl tohoto souboru) užívají titulky pro oddělení jednotlivých sekcí. V některých souborech vzorců je možné nacházet klíčové sekce všech vzorců pouhým obracením stránek. Je toho dosaženo tím, že všechny vzorce začínají na nové stránce a všechny sekce vzorců začínají zhruba na stejném místě stránky.
[Foote96] pro zvýraznění začátku vzorců účinně používá stínované titulky a návodné ilustrace.
Popisujete řešení nějakého problému v softwarovém návrhu. Máte určené Jasné cílené publikum, jež zahrnuje významné množství softwarových návrhářů nebo programátorů.
Jak napsat vzorec tak, aby dostatečně jasně a jednoznačně umožňoval přímočarou implementaci navrhovaného řešení?
Přidejte do vzorce jeden nebo více příkladů implementace daného návrhu. Zvolte programovací jazyk, který bude pravděpodobně srozumitelný pro vaše cílené publikum. Zvolte takový způsob implementace, který jasně a přímočaře demonstruje podstatu vzorce a zároveň maximálně omezuje nadbytečné nebo rušivé detaily. Zajistěte, aby všechny příklady kódů byly dobře komentovány a aby všechny předpoklady a učiněná rozhodnutí byly v textu explicitně uvedeny. Rozlište, které rysy vašeho příkladu jsou podstatné z hlediska návrhu popisovaného ve vzorci a které jsou podružné. Zajistěte, aby vaše příklady kódů byly doslova schopné běhu (tj. především kompletní a bez syntaktických chyb). Syntaktické chyby v příkladech kódů mohou být pro čtenáře stejně rušivé jako pro překladače.
Dobře komentovaný příklad kódu je formálním, precizním a jednoznačným zápisem softwarového návrhu. Zkušení programátoři tomuto zápisu navíc dobře rozumí. Pro všechny čtenáře je pak zdrojový kód potvrzením, že správně pochopili klíčové myšlenky vašeho vzorce.
Všechny vzorce uvedené v knize Design Patterns [GHJV95] obsahují Ukázky zdrojových kódů, což je přirozené, neboť je kniha určena pro programátory.
Ukázky zdrojových kódů jako bonus zajišťují, aby byl vzorec srozumitelný i bez čtení těchto kódů. Navíc mohou pomoci omezit rušivý vliv příkladů kódu na souvislost textu.
Jak zajistit, aby podstata vašeho softwarového návrhu popsaného vzorcem byla srozumitelná pro všechny čtenáře z cíleného publika, bez ohledu na to, zda znají určitý programovací jazyk?
Píšete vzorec softwarového návrhu nebo návrhu architektury a připojujete k němu Ukázky zdrojových kódů.
Zajistěte, aby byl vzorec dostatečně samostatný, dokázal předat podstatné části návrhu i kdyby byly ukázky zdrojových kódů odstraněny. Ukázky kódů připojujte jako bonus, který může pomoci čtenářům ověřit, že návrh pochopili, a představuje pro ně vodítko, jak návrh nejsnáze implementovat. Ujistěte se, že jsou ukázky kódů dobře začleněny do textu a mohou být snadno přeskočeny, nebo že jsou uvedeny v samostatné Přeskočitelné sekci.
Popisy významných algoritmů a klíčových vztahů mezi objekty by měly být uvedeny v jiné formě zápisu než v nějakém programovacím jazyce. Mezi použitelné formy zápisu lze řadit pseudokód, vývojové diagramy, záznamy o chodu událostí, popisy objektového modelu a vztahů mezi objekty. Ať zvolíte kteroukoli formu zápisu, pište Srozumitelné zápisy; netvořte vlastní formy zápisu a neužívejte málo známé formy, pokud to není naprosto nevyhnutelné.
Účelem vzorce je předat informace co nejširšímu možnému publiku. Pokud vzorec nebude zcela srozumitelný i bez čtení zdrojových kódů, čtenáři, kteří neznají zvolený programovací jazyk vzorci neporozumí.
Reader >> understandsSmalltalk "Answers True if the reader understands Smalltalk, otherwise signals an exception" self understands: #Smalltalk ifTrue: [^True] ifFalse: [self doesNotUnderstand].
V této kapitole najdete několik příkladů vzorců a "protivzorců" pro programátory. Protivzorce (Anti Patterns) jsou vzorce popisující cesty od problémů ke špatným řešením a výjimečně též vzorce popisující cesty od špatných řešení k dobrým řešením. Formálně se od běžných vzorců nijak výrazně neliší, snad jen vyjma důrazného varování: "Tudy ne!". Uvedené příklady vzorců pocházejí od různých autorů, a proto zároveň dobře ilustrují různé styly psaní vzorců.
Kromě vzorce jak psát Snadno srozumitelný kód se dozvíte, proč a jak se snažit vyhnout Brotnosauřím projektům a proč netrávit čas Navrhováním kuchyňského dřezu.
Bezprostředně za každým vzorcem následuje seznam odkazů na původní vzorec, sbírku vzorců na daném serveru a všechny další vzorce, na něž se tento odkazuje.
...na nejnižších úrovních programu jsou úseky kódu. Jsou to místa, jimž je nutné dobře rozumět, aby bylo možné měnit program, a podobně úplné porozumění programu vyžaduje porozumění těmto úsekům kódu.
* * *
V mnoha částech kódu je problém dezorientace velmi palčivý. Lidé nemají nejmenší tušení, k čemu která část složka kódu slouží, a zažívají proto významný duševní stres.
Představte si, že píšete část kódu, která není tak složitá, že by vyžadovala rozsáhlou dokumentaci, nebo není z hlediska účelu celého programu tak podstatná, aby její dokumentace stála za námahu, zvlášť, když kód je sám o sobě dostatečně srozumitelný. Jak můžete napsat takový kód?
Lidé potřebují na napsaný kód zírat, aby jej pochopili a získali dostatek sebedůvěry pro měnění kódu. Pokud musí trávit čas přecházením z okna do okna, listováním nahoru a dolů, aby našli příslušné části kódu, je zbytečně rozptylována jejich pozornost od pochopení smyslu kódu a získání sebedůvěry pro jeho změnu.
Lidé při čtení lépe porozumí věcem, jež jsou napsány v přirozeném směru čtení; v případě naší kultury je to obecně zleva doprava a shora dolů.
Jestliže kód není spolehlivě srozumitelný, bude omylem při změně poškozen.
Proto, uspořádejte významné části kódu tak, aby se vešly na jednu stránku. Napište kód srozumitelný pro člověka, který jej čte shora dolů. Nevynucujte opakované nahlížení do kódu pro to, aby čtenář pochopil, jak jsou užívány datové struktury a jak je v kódu předáváno řízení.
* * *
Tohoto vzorce lze dosáhnout pomocí následujících vzorců: Lokální proměnné definovány a použity na jedné stránce, usiluje o udržení všech lokálních proměnných na jedné stránce; Nastavte proměnné jedenkrát, usiluje o zmenšení nutnosti prohledávat opakovaně kód pomocí toho, že je hodnota proměnných měněna jen jednou; Lokální proměnné nastaveny znovu před dalším použitím, což učiní hodnotu proměnné zjevnou pro čtenáře, který čte kód shora dolů; Udělejte smyčky zjevné, což pomůže lidem porozumět i částem kódu, jež nejsou lineární, i při zachování lineárního čtení kódu; a používejte Funkce pro smyčky, což zabalí složité struktury opakovaní s několika stavovými proměnnými do úseků, z nichž je každý snadno srozumitelný.
-- Richard Gabriel
Síly: Programátoři mají velká ega. Zákazníci často nevědí, co chtějí. Programátoři často nechápou rozdíl mezi tím, co je nutné a co je "skvělé".
Řešení: Svoláte všechny programátory a návrháře do velké místnosti (jako v Návrhu podle výboru) a každý k produktu připojí, co chce. Tento proces rychle vyvolá zpětnou vazbu a každý začne přidávat další a další náměty.
Diskuse: Brontosaurovatění produktu může začít nebo pokračovat v kterékoli jeho fázi vývoje. Nejčastěji k němu dochází během analýzy, výsledkem je nekončící fáze analýzy (viz AnalysisParalysis) nebo nerealisticky ambiciózní specifikace. Ve fázi návrhu se vyznačuje přidáváním více zvonečků a píšťalek, než analýza vyžadovala, nebo pokusem o abstrakci úplně všeho dříve, než bylo cokoli konkretizováno. Ve fázi programování se vyznačuje kódováním, jež nikdy nekončí, neboť programátoři nepřestávají přidávat "ještě jednu vymoženost".
-- Kyle Brown s inspirací od Jima Copliena
V této kapitole naleznete stručná shrnutí vzorců, jež přesahují rámec tohoto referátu, ale na něž se vzorce v referátu odkazují. Všechny vzorce pocházejí ze stránky A Pattern Language for Pattern Writing.
Závěrem musím poznamenat, že v tomto referátu nenajdete zdaleka všechny vzorce, jež se k problematice vzorců váží. Můžete proto využít seznamu literatury a odkazů k získání dalších znalostí, na většině stránek však naleznete kromě podrobných a kvalitních rad i omluvu, že ještě mnoho práce zbývá... ...možná některá právě pro vás...
| Forma vzorce | ||
|---|---|---|
| Problém | Řešení | Vzorec |
| Jak popsat opakující se řešení určitého problému tak, aby bylo snadno použitelné i pro ostatní? | Napište své řešení formou vzorce (pattern). | Vzorec |
| Jak přehledně popsat řešení, aby bylo současně možné používat jeho různé části za různých okolností? | Rozdělte rozsáhlý problém a jeho velké řešení nebo postup na dílčí problémy a odpovídající řešení. Tyto vzorce shrňte do Souboru vzorců | Soubor vzorců |
| Dobré strukturování vzorců | ||
| Problém | Řešení | Vzorec |
| Jak se ujistit, že všechny potřebné informace jsou ve vzorci obsaženy? | Zajistěte, aby ve vaše vzorci nechyběla žádná z uvedených povinných sekcí. | Povinné sekce |
| Jak sdělit důležité informace, které se však nehodí do povinných sekcí? | Do vzorce lze přidat uvedené i další rozšiřující sekce. | Rozšiřující sekce |
| Jak zajistit, aby čtenář pochopil, proč bylo zvoleno právě popisované řešení? | Nehledě na zvolený styl vzorce zajistěte, aby síly byly jasně viditelné. | Viditelné síly |
| Dosažení lepší čitelnosti a srozumitelnosti | ||
| Problém | Řešení | Vzorec |
| Jak zajistíte, aby byl vzorec snadno srozumitelný pro zamýšlené publikum? | Jasně určete cílené publikum, skupinu lidí, jimž chcete své řešení sdělit. Mějte toto publikum na paměti při psaní svého vzorce. | Jasné cílené publikum |
| Jak maximálně zvýšit pravděpodobnost, že čtenář vašemu vzorci správně porozumí? | Používejte jen takové termíny, jimž typický člen publika pohodlně bez problémů porozumí. Ověřte si srozumitelnost terminologie na zástupci cíleného publika. | Terminologie na míru čtenářům |
| Jak zajistit, aby byly diagramy snadno pochopitelné pro celé vaše cílené publikum? | Užívejte v diagramech takové formy zápisu, které jsou pro cílené publikum pravděpodobně srozumitelné. | Srozumitelné zápisy |
| Jak pomůžete čtenáři vašeho vzorce, aby vzorci porozuměl v co nejkratším čase a usnadnil si tak hledání vhodného řešení? | Usilujte o Čitelnost na první pokus. Je to velmi obtížný úkol, ale lze uvést alespoň několik technik, jež vám mohou pomoci. | Čitelnost na první pokus |
| Jak čtenářům zjednodušit pochopení podstaty vzorce a přitom ve vzorci poskytnout dostatek informací nutných pro použití vzorce? | Jasně vyznačte oddíly Problém, Kontext a Řešení, podrobnější informace (například síly nebo ukázky zdrojových kódů) přidejte v jasně odlišených sekcích. | Přeskočitelné sekce |
| Jak usnadnit nalezení klíčových prvků vzorce, především sekcí Problém, Kontext, Síly a Řešení? | S ohledem na styl vašeho vzorce zvažte, které sekce čtenář potřebuje při vyhledávání, pokud se ke vzorci odkazuje. Začátky těchto sekcí výrazně označte. | Nalezitelné sekce |
| Jak napsat vzorec tak, aby dostatečně jasně a jednoznačně umožňoval přímočarou implementaci navrhovaného softwarového řešení? | Přidejte do vzorce jeden nebo více příkladů implementace daného návrhu. | Ukázky zdrojových kódů |
| Jak zajistit, aby podstata vašeho softwarového návrhu popsaného vzorcem byla srozumitelná pro všechny čtenáře z cíleného publika, bez ohledu na to, zda znají určitý programovací jazyk? | Zajistěte, aby byl vzorec dostatečně samostatný, dokázal předat podstatné části návrhu i kdyby byly ukázky zdrojových kódů odstraněny. | Ukázky zdrojových kódů jako bonus |
Cílené publikum Čitelnost na první pokus Čitelné odkazy na vzorce Fungující příklad Jasné cílené publikum Náčrtky vzorců Nalezitelné sekce Návodná jména vzorců Povinné sekce Přeskočitelné sekce Rejstřík termínů Rozšiřující sekce Shrnutí souboru vzorců Shrnutí typu Problém/Řešení Snadno srozumitelný kód Soubor vzorců Srozumitelné zápisy pro diagramy a ilustrace Terminologie na míru čtenářům Titulky rozlišující strukturu Ukázky zdrojových kódů Ukázky zdrojových kódů jako bonus Viditelné síly Vzorec Zdrojové kódy jako bonus Zvýrazněný společný problém