[OSy] Informace k odevzdani semestralek

[Martin Decky]

Vazeni kolegove,

vzhledem k tomu, ze datum pro odevzdani semestralnich praci z OSu se
rychle blizi, posilam nekolik informaci pro pripomenuti a upresneni:


a) Posledni mozne datum pro odevzdani je patek 20. 2. 2009, soucasti
odevzdani je take osobni predvedeni funkcnosti a dokumentace (tento akt
zabere typicky asi 20 - 30 minut na skupinu). Na presnem terminu se
muzeme domluvit osobne nebo emailem.

Pokud se rozhodnete odevzdat sve reseni drive nez 20. 2., muzete
pochopitelne az do 21. 2. 00:00 CET sve reseni doplnit nebo opravit
pripadne nedostatky jak v kodu, tak v dokumentaci.

Pokud se naopak z praktickych duvodu ukaze, ze neni mozne stihnout
osobni predvedeni do 20. 2., muzeme se domluvit na pozdejsim terminu,
ale za odevzdane reseni budeme povazovat stav repository k 21. 2. 00:00
CET. Zadne pozdejsi upravy nebo doplneni nebudeme akceptovat, abychom
zadnou skupinu nezvyhodnovali.


b) Upozornuji, ze 20. 2. je take termin pro predvedeni *milestone
vyberovych zadani*, coz je nutna podminka pro pozdejsi hodnoceni
vyberovych zadani. Pod terminem milestone se mysli software ve stavu
alespon alfa-verze, tedy neco, co lze spustit a ma to nejakou, i kdyz
omezenou funkcnost ve smyslu zadani (na stabilitu, uroven kodu nebo
dokumentace se v teto fazi nehledi). Nestaci tedy jen (nespustitelna)
specifikace nebo slovni popis.

Z milestone musi byt zrejme, ze pracujete na reseni a postupujete
alespon ramcove spravnym smerem.


c) Pokud vite o nejake okolnosti, ktera Vam zasadne brani dodrzet termin
odevzdani, dejte nam zavcas vedet (je-li to jen trochu mozne, tak jeste
pred dnem 20. 2.). Za objektivni duvod pro odlozeni terminu odevzdani
povazujeme napriklad delsi nemoc clena tymu (musi byt dolozena
neschopenkou od lekare) a podobne.


d) Doporucuji znovu se podivat na slajdy z uvodniho cviceni pro
pripomenuti kriterii, podle kterych budeme semestralky hodnotit. Myslim,
ze nyni muzete diky nabytym zkusenostem lepe chapat nektere poznamky,
ktere Vam nemusely byt na zacatku semestru zcela jasne.

http://dsrg.mff.cuni.cz/~ceres/sch/osy/download/20080902-NSWI004-Agenda.pdf

Velmi strucne shrnuto:

* Pruchod testy neni nutna podminka, ale pouze jedno z kriterii
  (zapocitava se do kvality implementace), presto je vhodne, aby Vase
  finalni reseni proslo idealne vsemi testy vsech fazi.

* Kvalita kodu ma stejnou vahu jako funkcnost a kvalita dokumentace.
  Snazte se tedy o to, aby odevzdavany kod byl prehledny, vhodne
  komentovany, konzistentni atd.

* Dokumentace je v zasade dvojiho druhu. Nezbytkou je rucne psana
  dokumentace popisujici vlastnosti reseni, celkovou architekturu,
  pouzite algoritmy z pohledu "z prvniho patra", informujici ctenare o
  tom, kde ve zdrojovych souborech nalezne implementovane ktere casti
  apod. Soucasti hodnoceni teto dokumentace je i Vase drivejsi ustni
  prezentace na cviceni.

  Doplnujici je referencni dokumentace, tedy dokumentace vygenerovana
  automaticky primo ze zdrojovych kodu. Aby byla tato dokumentace vubec
  k necemu pouzitelna, musi byt v kodu dusledne pouzivany dokumentacni
  komentare a to u vsech dulezitych entit (souboru, datovych typu,
  globalnich promennych, funkci, maker atd.). Neni mnoho horsich veci
  nez derava referencni dokumentace, ktera neobsahuje popis poloviny
  veci, ktere v ni ctenar hleda.

  Obe casti dokumentace neni nutne striktne oddelovat, naopak je vhodne
  vyuzit nastroje pro generovani referencni dokumentace k propojeni obou
  casti (tak, aby napriklad mezi rucne psanou a referecni dokumentaci
  vedly vhodne odkazy).

* Pokud je soucasti Vaseho rozsireneho zadani take povinnost vypracovat
  nejake porovnani, je potreba vysledky (tabulky, grafy, slovni
  komentar) uvest v dokumentaci. Nestaci, ze jste meli vysledky
  v prezentaci.

  Je asi take jasne, ze dokumentace je to spravne misto pro uvedeni
  faktu, ze jste ve Vasem reseni implementovali neco nad ramec zadani.
  (Pokud nam to reknete jen ustne pri odevzdani, hrozi, ze na to
  zapomeneme a v kodu to prehledneme.)


e) Prakticka poznamka: Pokud pouzivane nastroj pro generovani referencni
dokumentace (napr. Doxygen) a budete generovat HTML soubory, tak

- bud nastavte nastroj tak, aby negeneroval kvatna malych souboru, nebo
- do repository je necommitujte jednotlive, ale zabalene v jednom
  archivu, nebo
- referencni dokumentaci do repository necommitujte vubec a prilozte
  pouze skript nebo konfiguracni soubor pro jeji vygenerovani.

Motivaci je to, ze prace s repository obsahujici spoustu malych souboru
je zbytecne pomala a navic referencni dokumentace neni neco, co by bylo
potreba samostatne verzovat (lze ji vzdy vygenerovat ze zdrojaku).


Pokud jsem snad na neco zapomnel nebo mate nejakou nejasnost ci dotaz
tykajici se odevzdavani nebo hodnoceni, prosim nevahejte vyuzit mailing
list k polozeni dotazu.

Preji hodne zdaru pri dokoncovani Vasich reseni!


M.D.