[OSy] Informace k finalnimu odevzdavani

[Martin Decky]

Vazeni kolegove,

protoze se kvapem blizi termin odevzdani rozsirenych zadani 
semestralnich praci z OSu, posilam drive slibene organizacni informace.


1) Za odevzdanou semestralku budeme povazovat stav Vaseho SVN repository 
k casu 19. 2. 2011 00:00 CET (jako obvykle se budeme divat bud na /trunk 
nebo na jinak vhodne intuitivne pojmenovany adresar, napr. /branches/final).

Zduraznuji, ze soucasti repository musi byt k tomuto casu vse, co si 
prejete zahrnout do Vaseho finalniho reseni. Na cokoliv, co nam 
napriklad poslete emailem nebo commitnete do repository po deadline, 
nebudeme brat zretel (az na mimoradne a explicitne povolene vyjimky).


2) Jako obvykle pri odevzdavani dila tohoto rozsahu je vhodne vyvarovat 
se zasadnich zmen a prepisovani tesne pred odevzdanim. I v pripade, ze 
Vam neco trochu nefunguje, radeji se to nepokousejte zurive na posledni 
chvili opravit, protoze muzete nechte rozbit neco jineho. Hodnoceni 
finalniho reseni nebude rozhodne binarni, takze se v nem mohou pozitivne 
odrazit dobre minene zamery, ale bohuzel negativne i nesmysly, ktere jen 
shodou okolnosti nahodou funguji.

Tech nekolik poslednich zbyvajicich dnu je vhodne venovat uprave a 
unifikaci zdrojovych kodu (aby cela semestralka mela jednotny coding 
style), dopisovani dokumentace atd.


3) Pokud pouzivate nejaky nastroj pro referencni dokumentaci (napr. 
Doxygen), prosim necommitujte do repository vystup tohoto nastroje. 
Typicky se totiz jedna o stovky malinkych HTML a PNG souboru, ktere 
jednak nema valny smysl samostatne verzovat a jednak to zdrzuje pri 
checkoutu repository. Bohate postaci, kdyz bude mozne referencni 
dokumentaci snadno ze zdrojoveho stromu vygenerovat.

Naopak, pokud budete mit nejakou rucne psanou dokumentaci vytvorenou 
nejakym nezavislym prostredkem (napr. v beznem word processoru), potom 
je samozrejme na miste, abyste do repository commitnuli treba export ve 
formatu PDF pro pohodlne cteni.

Pripominam, ze mnohdy je velmi uzitecne, aby rucne psana a generovana 
dokumentace spolu byly vhodne hypertextove provazany (aby ctenar mohl 
snadno prechazet od "high-level" popisu k "low-level" dokumentaci a 
pripadne i zpet). Proto byva velmi caste, ze i rucne psana cast 
dokumentace je soucasti vstupu pro generovani referencni dokumentace a 
tvori s ni jeden celek.

Dokumenaci samozrejme neni potreba tisknout, chranme nase stromy :)


4) Soucasti odevzdani semestralky je take jeji osobni predvedeni, ktere 
trva typicky 20 - 30 minut a behem ktereho se Vam pokusime dat hruby 
odhad bodu, ktere pravdepodobne za semestralku ziskate.

Jako vhodny cas pro toto osobni predvedeni se mi jevi streda 23. 2. mezi 
12:00 - 17:00 a patek 25. 2. mezi 9:00 - 17:00. Prosim napiste mi, jaky 
konkretni cas by se Vam v ramci techto bloku hodil. V nejhorsim se 
samozrejme muzeme domluvit i na zcela jinou dobu, ale bylo by vhodne s 
tim prilis neotalet.

Na predvedeni samozrejme nemusi prijit vsichni clenove tymu, staci jen 
jeden zastupce, ale kompletni sestava byva typicka.


5) S bodem 4 souvisi pochopitelne i predvedeni vyberovych semestralek. 
Prosim tedy vsechny autory vyberovych semestralek, aby se se mnou 
domluvili na osobnim predvedeni.


6) V prubehu brezna se pokusime detailne projit Vase reseni a poslat Vam 
podrobne bodove hodnoceni a finalni pocet bodu. Doporucuji projit si 
znovu slajdy z uvodniho cviceni, abyste si pripomneli, podle jakych 
kriterii budeme Vase semestralky hodnotit. Verim, ze nektere veci z tech 
slajdu teprve ted budou davat smysl.

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

Velmi strucne shrnuji:

* Pruchod testy jiz neni nutna podminka, ale pouze jedno z kriterii pro
   hodnoceni rozsireneho zadani (zapocitava se do kvality implementace).
   Presto je vhodne, aby Vase finalni reseni proslo idealne vsemi testy
   vsech zakladnich zadani a pripadne i testy rozsireneho zadani,
   jsou-li k dispozici.

* Kvalita zdrojovych kodu ma stejnou vahu jako funkcnost a kvalita
   dokumentace. Snazte se tedy o to, aby odevzdavane zdrojaky byly
   prehledne, upravene, vhodne komentovane, konzistentni, bez
   zakomentovanych "marnych pokusu", pomocnych ladicich funkci atd.

* Snazte se take dodrzet pozadavky na pouziti vhodnych programatorskych
   prostredu, tedy vhodnou volbu algoritmu a datovych struktur
   (predevsim z hlediska efektivity pro nejtypictejsi pripad pouziti v
   danem kontextu), vhodne oddeleni ruznych urovni abstrakce v kodu atd.

* Rucne psana dokumentace je v zasade nezbytna. Mela by popisovat
   obecne vlastnosti Vaseho reseni, celkovou architekturu, pouzite
   algoritmy z "high-level" pohledu, mela by informovat ctenare o tom,
   kde ve zdrojovych souborech nalezne jejich konkretni implementace
   atd. Soucasti hodnoceni dokumentace je samozrejme i Vase drivejsi
   ustni prezentace na cviceni.

   Doplnujici je referencni dokumentace. Aby byla referencni
   dokumentace vubec k necemu uzitecna, 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
   obsahuje popis jen poloviny veci ze zdrojaku.

* Pokud je soucasti Vaseho rozsireneho zadani take povinnost vypracovat
   nejake porovnani, je potreba vysledky (tabulky, grafy) uvest v
   dokumentaci a je potreba pripojit Vas slovni komentar nebo
   vyhodnoceni (tedy nestaci jen surova data bez dalsiho zpracovani).


7) Pokud jste v ramci Vaseho reseni implementovali neco nad ramec zadani 
nebo pouzili nejaky mimoradne zajimavy postup, urcite je vhodne uvezt to 
v dokumentaci -- i pri podrobnem prochazeni zdrojaku muze totiz hezka 
myslenka snadno zapadnout.

Plati to ovsem i obracene: Pokud vite, ze jste neco ze zadani nestihli 
nebo neco nechoti tak, jak by melo, uvedte to v dokumentaci. Pomuze nam 
to lepe ohodnotit rozsah takoveho "problemu" a lepe poznat, zda to, co 
vidime ve zdrojaku, je jen nedokonceny pokus o implementaci a ne neco, o 
cem si chybne myslite, ze by vlastne melo fungovat.


8) Pokud vite o nejakych zavaznych duvodech, ktere Vam brani v beznem 
odevzdani semestralky podle zde uvedeneho postupu, dejte nam prosim co 
nejdrive vedet.


V pripade libovolnych nejasnosti, dotazu nebo pripominek prosim 
nevahejte vyuzit tuto konferenci. Preji vsem hodne zdaru pri odevzdavani!


M.D.