Požadavky na RP, BP, DP, SWP

Jako zásadní problém pražských technických univerzit vnímám velice rozdílné požadavky na kvalitu ročníkových projektů (RP), bakalářských prací (BP), diplomových prací (DP), softwarových projektů (SWP), apod. ze stran vedoucích, oponentů a hodnotících komisí. Co projde jako diplomka v jedné komisi či u jednoho oponenta nemusí projít ani jako bakalářka v komisi jiné, či u jiného oponenta. Při posuzování prací často narážím na stále stejné nedostatky, a zároveň řešitelům prací opakuji stále stejné požadavky. Pro eliminaci opakování a pro vyšší transparentnost zde uvádím svůj seznam požadavků na jednotlivé typy prací. K tomuto textu lze dávat připomínky pomocí GitHubu.

Obsah

Společné technické požadavky na softwarová díla

Ať už pracujete na ročníkovém projektu, nebo finišujete s diplomkou, jejíž částí je softwarové dílo, existují společné požadavky na to, co by toto dílo mělo splňovat. Seznam můžete použít jako checklist před odevzdáním - já ho používám jako checklist při hodnocení.

  1. SW je vyvíjen v systému pro správu verzí (GitHub, GitLab). Jedná se o školní dílo, a zpravidla není důvod pro to, aby repozitář nebyl veřejný.
  2. SW je řádně zdokumentován, včetně licence. Doporučuje se licence MIT.
  3. SW lze snadno nasadit, včetně testovacích dat. V době Dockeru není důvod, aby tento proces měl více jak cca 3-5 kroků, které lze pomocí copy&paste provést. Myslete na oponenta, recenzenta publikace a nebo autora přehledového článku, který bude za 5 let chtít váš SW vyzkoušet.
  4. Pokud to lze, SW má běžící online demo. To lze zařídit pomocí GitHub pages, Heroku, školní virtuálky po dohodě s vedoucím, apod.
  5. SW je funkční. Pokud SW nasadím, spustím a on spadne nebo nedělá to, co se v dokumentaci píše, je to špatně.
  6. SW se chová slušně, tzn. žádné nedokumentované sledování, žádné vyžírání prostředků při jen trochu delším běhu, apod.
  7. Případné chybové hlášky jsou deskriptivní, je jasné co se pokazilo a co se s tím má dělat. Tedy žádné "Unknown error", "Unexpected error", "This should not happen", "Oops".

Ročníkový projekt (RP)

Ročníkový projekt na MFF UK vede vedoucí a uděluje za něj zápočet. Posudek oponenta zde není vyžadován. RP je nejčastěji řešen jako první část bakalářské práce.

Požadavky na zápočet za RP

  1. Kompletní specifikace výsledného software. Ty zahrnuje:
    Analýza
    Strukturované funkční a nefunkční požadavky, use casy (případy užití) a jejich popis, včetně scénářů práce se SW. Na MFF je toto pokryto předmětem NSWI041 - Úvod do softwarového inženýrství.
    Návrh
    Jaké části SW bude mít, které technologie a nástroje byly zvažovány pro jejich implementaci, pomocí jakých kritérií, a které a proč byly vybrány
  2. Zárodek implementace
  3. Zadání navazující bakalářské práce. To "vykopne" řešitel a dotvarujeme ho společně v okamžiku, kdy je jasnější, co vznikne.

Proces řešení RP

Stanovení parametrů je nejprve na řešiteli, dále pak na vedoucím podle toho, jak práce postupují.

Forma
Pravidelné konzultace nebo videoreporty formou 3minutového screencastu s tím, co je od minule nového
Frekvence
Nejprve jednou za 14 dní, později dle potřeby
Nástroje
Pro textovou část online LaTeX editor Overleaf
Pro softwarovou část veřejný repozitář na GitHub. V případě obavy o ochranu osobních informací pak fakultní instance GitLab.

Softwarový projekt (SWP)

Softwarový projekt (SWP) na MFF UK má za cíl, aby si studenti vyzkoušeli práci v týmu, práci na rozsáhlejším softwarovém díle a typické fáze vývoje softwarového díla, tedy sběr požadavků, tvorbu specifikace, implementaci, testování, prezentaci a údržbu. Řešení SWP má 2 formální části. Tvorbu specifikace a vlastní implementaci. Věcně by SWP měl být dokumentován jako každé jiné softwarové dílo. Fáze specifikace končí dokumentem pokrývajícím části Úvod, Analýza a Návrh. Fáze implementace končí dokumenty obsahujícími jednotlivé dokumentace, tedy uživatelskou, administrátorskou a programátorskou. Uživatelská dokumentace pak obsahuje i kapitoly vyhodnocení, testování a závěr.

Specifikum SWP je, že se od něj opravdu vyždaduje, že je odladěn, a tedy funkční, s řádně ošetřenými chybovými stavy. SWP tedy při testování oponentem a při obhajobě nesmí spadnout.

Proces řešení SWP

Forma
Pravidelné osobní konzultace
Frekvence
Týdenní, později dle potřeby
Nástroje
Pro textové části online LaTeX editor Overleaf
Pro softwarovou část veřejný repozitář na GitHub. V případě obavy o ochranu osobních informací pak fakultní instance GitLab.

Bakalářská práce (BP), Diplomová práce (DP)

Mnou vedené bakalářské jsou převážně typu "softwarové dílo", případně doplněné o snadnější výzkumný problém. U diplomových prací jde zpravidla o náročnější výzkumný problém, či softwarové dílo většího rozsahu. Formální požadavky na BP a DP se ale neliší. Základní podmínkou pro úspěšné dokončení BP či DP, na které se ale překvapivě často zapomíná, je splnění zadání. Tedy vše, co je napsáno v zadání, musí být nějak zpracováno ve výsledné práci, ať už vyřešením, nebo opodstatněným zdůvodněním, proč ta část zadání splněna není, a jaké pokusy o splnění byly podniknuty. Jinak se struktura BP a DP typu "softwarové dílo" řídí strukturou dokumentace softwarového díla.

Proces řešení BP a DP

Stanovení parametrů je nejprve na řešiteli, dále pak na vedoucím podle toho, jak práce postupují.

Forma
Pravidelné konzultace nebo videoreporty formou 3minutového screencastu s tím, co je od minule nového
Frekvence
Nejprve jednou za 14 dní, později dle potřeby. Nežádoucí je zejména nenadálé přerušení prací studentem a jeho "odmlčení se".
Nástroje
Pro textovou část online LaTeX editor Overleaf
Pro softwarovou část veřejný repozitář na GitHub. V případě obavy o ochranu osobních informací pak fakultní instance GitLab.
Termíny
Práce musí být ze strany studenta finální minimálně 14 dní před oficiálním termínem odevzdání. Školitel pak musí práci detailně projít a mít finální poznámky, které následně student musí mít čas zapracovat. Plnění termínů je plně na studentovi.

Obecné požadavky na dokumentaci softwarového díla

Dokumentace softwarového díla se odevzdává buď jako textová část BP či DP typu "softwarové dílo" či jako specifikace a dokumentace softwarového projektu. Musí obsahovat následující části:

Úvod
Úvod je psán pro neodborníka. Uveďte kontext, ve kterém je práce řešena tak, aby ho pochopil každý. Uveďtě, v jaké situaci v reálném světě se uživatel vašeho SW nachází, když by mu užití vašeho SW mělo pomoci, a jak. Nechte ho přečíst a připomínkovat (pra)rodiče.
Analýza
Uživatelské role, tj. kdo jsou lidé, kteří typicky přijdou do styku s vaším dílem? Co musí znát za technologie? S čím jim dílo pomůže? Strukturované funkční a nefunkční požadavky, use casy (případy užití) a jejich popis, včetně scénářů práce se SW. Na MFF je toto pokryto předmětem NSWI041 - Úvod do softwarového inženýrství. Zde je třeba ukázat, pro koho a co bude dílo dělat, nikoliv jak - nemá smysl řešit jak, když nevíme co. Toto typicky vyplývá z komunikace s vaším klientem, v případě školních prací tedy vedoucím práce či firemním konzultantem. Nezpomeňte zmínit, kde se identifikované požadavky vzaly. Konzultovali jste potenciální uživatele, nebo jste si vy představili co by asi tak chtěli? Obojí je ok, ale je třeba ten proces popsat.
Potom, co je jasné, co má váš SW umět, je potřeba udělat přehled již existujících řešení. Nedá se předpokládat, že váš SW bude tak inovativní, že nikdy nic ani vzdáleně podobného neexistovalo. Vždy se nějaká podobná řešení najdou a je třeba je najít, popsat a srovnat. Je třeba si rozmyslet a popsat, jaká kritéria budete pro srovnání jednotlivých řešení používat. Dále každé existující řešení je třeba popsat jednak slovně a jednak strukturovaně, pomocí identifikovaných kritérií. Na závěr této sekce patří tabulka, ve které jednotlivá řešení přehledně srovnáte dle kritérií. Sem můžete zahrnout i to své, nové řešení, a jasně ukázat, v čem je jiné a lepší.
Návrh
Zde se soustředíme na to, JAK implementovat to, co je v Analýze specifikováno. Tzn. jaké části SW bude mít, které technologie a nástroje byly zvažovány pro jejich implementaci, pomocí jakých kritérií, a které a proč byly vybrány.
Implementace
Jakékoliv zajímavé detaily zahrnující například odchylky od návrhu či jeho upřesnění, které vyplyne z potřeb během samotné implementace software.
Uživatelská dokumentace
Screenshoty, popis typických scénářů z Analýzy, ale ilustrovaných na implementovaném SW. Tj. co všechno a jak může uživatel se softwarem dělat. Pro scénáře je třeba mít připravena data, a, pokud možno, živou instanci pro testování tak, aby oponent mohl scénáře projít. Ideálně je hostovaná na GitHubu jako GitHub Pages.
Vývojářská dokumentace
Zahrnuje komentáře v kódu, a její část může být i generovaná. Nicméně musí zahrnovat i ručně psanou část pro vývojáře, který k vašemu SW přijde a měl by mu porozumět tak, aby byl schopen ho rozšířit a pokračovat v jeho vývoji. Ideálně je hostovaná na GitHubu jako GitHub Pages.
Administrátorská dokumentace
Obsahuje instrukce pro administrátora pracovní stanice nebo serveru, kam je třeba vaše řešení nasadit. Takovým administrátorem je i oponent. Musí zahrnovat kompletní požadavky na prostředí, tj. OS a jeho verze, potřebné knihovny atd. Musí obsahovat odkaz na GitHub/GitLab repozitář, kde byl SW vyvíjen, a který tag/commit je ten, který byl s prací odevzdán. Musí zahrnovat stručné a jasné instrukce, jak software naklonovat z repozitáře, jak jej zbuildit a spustit. V době Dockeru není důvod, aby takové instrukce zahrnovaly více jak 3-4 copy"paste kroky. Ověřte si, že na čerstvě nainstalovaném PC (virtuálce) lze software (včetně testovacích dat) dle instrukcí rozběhnout a projít uživatelské scénáře. Ideálně je administrátorská dokumentace hostovaná na GitHubu jako GitHub Pages, nebo je přímo obsahem README.md souboru v kořeni repozitáře.
Evaluace
Pokud SW implementuje nějaký algoritmus či proces, měla by tato část obsahovat popis vyhodnocení jak bylo ověřeno, že SW pracuje správně, tj. dělá co má, vzhledem k tomu, co měl implementovat.
Testování
Obsahuje přehled toho, jak byl software testován. To typicky zahrnuje unit testy (jejich počet, pokrytí kódu), výkonnostní testování (jaký HW, jaká část SW jak dlouho tvala) a uživatelské testování (jaký scénář, kolik lidí, přehled zpětné vazby). Pro vyhodnocení použitelnosti na základě uživatelského testování lze úspěšně použít System Usability Scale (SUS), což je obecná, široce používaná sada otázek a metodika k jejich vyhodnocení.
Závěr
Co se povedlo, co se nepovedlo, co je nově možné pomocí SW dělat a jak by šlo do budoucna SW rozšiřovat

Další tipy pro textovou část