Co musí obsahovat textová dokumentace k řešení projektů z APR - PRO.
Datum poslední modifikace: 14.2.2003
Dokumentace ke každému projektu se skládá z osmi částí:
- Titulní stránka
Vzhledově stejná pro všechny dokumenty (doporučuji si pro ni vytvořit šablonu), obsahuje identifikační údaje. Název fakulty (je možné použít logo FIT), do kterého předmětu dokumentace patří (APR/PRO), název projektu podle zadání, jméno autora dokumentu, login, datum.
- Obsah
Úroveň detailu (zda budou uvedeny sekce N, nebo i N.N, nebo dokonce N.N.N) zvolte vhodně podle délky a složitosti dokumentu. Pokud dokument obsahuje množství obrázků a/nebo tabulek, je vhodné vytvořit a za obsah připojit také seznam těchto elementů. Pro dokumenty do cca 5 stránek délky není nutný.
- Úvod
Stručný a jasný přehled, čeho se dokument týká a jaké má části.. Úvod je nutnou součástí každého dokumentu. Stačí dva, maximálně tři odstavce. Mají být napsány tak, aby čtenář dokumentu nemusel už dál číst a přesto měl přehled o celém dokumentu.
Pokud se jedná o dokument hemžící se zkratkami a akronymy, je nutné uvést pododdíl s vysvětlující tabulkou (zkratka, plný text). Je vhodné zde také uvést odkazy na zdroje, odkud bylo čerpáno obeznámení se s danou problematikou, odkazy na literaturu o používaných metodách apod.
- Analýza problému a princip jeho řešení
Obsahuje stručnou charakteristiku řešeného problému. Princip řešení, popis funkcí, vymezení vstupních dat a požadovaných výsledků, možná omezení, možný rozsah hodnot dat. Je možné použít slovní formu doplněnou obrázky, schématy, tabulkami apod. (např. tabulka by mohla obsahovat sloupce: Funkce: ..., Popis: ..., Vstupy: ..., Výstupy: ..., Podmínky: ......), nebo: Diagramy datových toků - grafická technika, modelující toky dat a jejich transformace (různé názvy: bubble chart, bubble diagram, process model, function model, work flow diagram) .
- Návrh řešení problému
Výběr, či vytvoření metody řešení, resp. vytvoření matematického modelu, volba a sestavení algoritmu. Dekompozice problému. Stanovení vhodných datových typů, názvů procedur a funkcí, specifikace parametrů procedur a funkcí. Formát zobrazení výsledků. Možná forma: slovní popis, vývojové diagramy, Nassi Schneidermanovy diagramy, symbolika vyššího programovacího jazyka, či kombinace těchto forem.
!!! Nebude zde okopírovaný celý program v Pascalu!!!!
- Specifikace testů
Obsahuje popis alespoň 10 testovacích případů, kterými se bude ověřovat funkčnost a/nebo výkonové vlastnosti programu nebo jeho podprogramů. Je nutno zdůvodnit výběr testovacích případů, testovacích dat a metodiky testování. Návrh testů bude zaměřen např. na možné: chyby zvolené metody, chyby vstupních dat, chyby zobrazení. Může být i ve formě tabulky.
Možná šablona pro specifikaci testů (pro každý test):
Testovací údaje č.: XX
Testovací kritérium: <popis vybraného testovacího kritéria>
Testovací vstupy/očekávané výstupy: konkrétní dvojice
další vstup/výstup; může jich být na základě příslušného kritéria více
Výsledek testování: zda se odhalila nějaká chyba testováním a jaká - její popis
Poznámky: jakékoliv další významné poznámky k tomuto testovacímu kritériu.
- Popis vlastního řešení (implementace)
Obsahuje popis vlastního řešení (implementace) a problémů, se kterými jste se při řešení setkali. Při popisu principu řešení nepoužívejte "algoritmické" formy (když A je rovno 5 pak...). Tvořte souvislé české věty. Snažte se o ABSTRAKTNÍ a CO NEJSTRUČNĚJŠÍ popis, který je ale co do obsahu vyčerpávající a věcně správný. Nezabývejte se detaily, pokud to nepovažujete za zajímavé z hlediska řešení. Neopisujte doslova zadání jednotlivých procedur, protože jsou často kvůli jednoznačnosti příliš podrobná. Vyjádřete se vlastními slovy. Nepopisujte každou proceduru zvlášť, účelem není velký objem textu, ale vystižení podstaty. V dokumentačním souboru předpokládejte pouze znalost zadání. Neodkazujte se na komentáře ve zdrojovém textu.
- Závěr
V závěru dokumentace uveďte zdroje odkud jste čerpali informace k projektu - eventuelně zdroj vzorových algoritmů, vlastní zajímavé postřehy z celkového řešení problému a metriky vytvořeného produktu:
počet procedur a funkcí počet řádků zdrojového kódu velikost kódu programu velikost statických dat (proměnné a konstanty)
Další doporučení
Dokumentace tvoří samostatný celek. Dokumentace k projektům vás má naučit psát česky (slovensky, anglicky). Proto bude mít podobu slohového cvičení a ne strohého, heslovitého popisu. Nepodceňujte ji. Dosavadní zkušenosti ukazují, že je to pro mnohé velmi těžký úkol. Uvědomte si, že svá díla budete v budoucnu prodávat lidem, kteří neumějí programovat. Zato český (slovenský, anglický) jazyk ovládají mnozí velmi dobře. Dodržujte pravidla českého pravopisu. Stále ještě existují nějaké vzory a vyjmenovaná slova. Vaše skvělé dílo si nikdo nekoupí, pokud ve vašich textech nalezne hrubky typu i/y, s/z, mně/mě a podobné. Nebude prostě důvěřovat tomu, že umíte programovat, když neumíte ani svůj vlastní jazyk.
Odstavce zpřehledňují text. Při čtení textových souborů v elektronické podobě (neproporcionální písmo, holý ASCII text) je vhodné oddělovat odstavce prázdným řádkem. Nepoužívejte příliš mnoho zvýrazňujících prvků (nadměrné podtrhávání, řádky hvězdiček a podobné grafické prvky). Někdy méně znamená více. Nepoužívejte osobních a citově zabarvených obratů ("Zdá se mi, že by se mohlo..."). Vyjadřujte se decentně, jako kdyby na vašem textu mělo záviset, zda vás přijmou do zaměstnání, či ne. Z popisu může vyplývat, že máte smysl pro humor, ale vyvarujte se laciných "srandiček". Zvlášť nepříznivě to působí v případech, kdy chybí fakta a věcná správnost. Dokumentace se píše pro někoho jiného, než pro vás. Nepoužívejte tvrzení typu: "Vzhledem k tomu, že procedury, které jsem v této části řešil, jsou krátké a velmi průzračné, obsáhlejší komentář nemá smysl." Také hodnocení typu "tato procedura je jednoduchá" (následuje-li popis) si nechejte pro sebe. Co je jednoduché pro vás, nemusí být jednoduché pro někoho jiného. Pokud píšete texty neproporcionálním písmem (ascii text v elektronické podobě, t602 a podobné), nepoužívejte zarovnávání textu na pravý okraj. Mezi slovy vznikají velké mezery, které zhoršují čitelnost textu. Jediné, co je na uvedeném způsobu hezčí, je vzhled z větší vzdálenosti. Pokud budete někomu posílat úřední dopisy, u kterých předpokládáte, že je nikdo nebude číst, pak je vizuální dojem účinný (vypadá to hezky).
Dávejte pozor na psaní mezer v okolí interpunkčních znamének. Pokud uvádíte vloženou větu do závorek, nepište za otvírací závorkou a před zavírací závorkou mezeru. ( NEPIŠTE TO TAKTO ), ale (TAKTO). Totéž co platí o závorkách platí i o uvozovkách. Před interpunkčními znaménky (čárka, tečka, dvojtečka, otazník, středník, vykřičník) se mezera nedělá. Naopak za interpunkčními znaménky se dělá vždy. Při psaní na počítači nerozdělujte ručně slova. Pokud byste něco podobného později zpracovávali, dost se to "tvrdým" rozdělováním komplikuje. Nevytvářejte dlouhá, krkolomná souvětí. Přečtěte si, co jste to vlastně napsali. Zhodnoťte, jak by se vám to líbilo, kdyby to napsal někdo jiný. Pokud se jedná o samostatnou práci, kterou prokazujete své znalosti, nepoužívejte v dokumentaci množné číslo (řešili jsme... - my Ludvík XIV). Něco jiného je to v případě, kdy prezentujete něco nového. V tom případě předpokládáte účast čtenáře jako aktivního posluchače a promlouváte k němu jako ve vzájemném dialogu.
Některá cizí slova se skloňují jinak než v češtině. Pokud se například provádí KOMPRESE textu, pak je výsledkem KOMPRIMOVANÁ posloupnost (ne kompresovaná). V tomto případě si vzpomeňte na OVOCNÝ KOMPRIMÁT LIPO. Není chybou, pokud používáte zkrácená slova typu např., apod., tzv., aj. - v tom případě ale musí být zakončena tečkou. Nepoužívejte zkratková slova, která v běžném životě nejsou často k vidění: fa. (firma), pí. (paní) a podobná. Při psaní souvislého textu bývá vhodné zkratková slova nepsat vůbec. Raději je rozepište úplně (například, podobně, a tak dále). Často si v těchto případech uvědomíte, že jste vlastně nepoužili nejvhodnější spojení.
Zde je k dispozici RFF free trial version pro pohodlné kreslení různých diagramů.
Kreslíková, únor 2003
Algoritmy a programování | Programovací seminář | Informace k projektům
