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