Dokumenteerimine ja koodistiil


Selle harjutustunni eesmärk on tutvuda programmide dokumenteerimisega javadoc abil ja Java koodistiili mõistega.

Programmeerimise lahutamatuks osaks on programmide dokumenteerimine selleks, et teised inimesed saaksid neid kasutada. Keeles Java on välja kujunenud standardne viis dokumentatsiooni esitamiseks html-formaadis (vt. näit. Java API kirjeldust). Dokumentatsioon aitab kiiresti leida klasside seoseid teiste klassidega, olemasolevaid meetodeid ning meetodite signatuure, viiteid antud teemaga seotud lehtedele jne. Java arendusvahendite komplektis on programm javadoc, mis genereerib nõutud formaadis dokumentatsiooni programmi tekstis leiduvate eriliste javadoc-kommentaaride järgi.

Tutvuge materjalidega javadoc kohta Oracle lehel (enne või pärast harjutustundi lugege neid põhjalikumalt).

Praktilise tööna tuleb teil dokumenteerida üks programm.
  1. Looge eraldi kataloog (kaust) selle  harjutustunni jaoks (mkdir), soovitavalt public_html alampuusse, et saaks genereeritud dokumentatsiooni veebilehitsejaga vaadata (loomulikult saab vaadata ka lokaalset faili).  Muutke see kataloog jooksvaks kataloogiks (cd).
  2. Salvestage programmi Kellad.java lähtetekst sellesse kataloogi.
  3. Lisage programmi teksti javadoc-kommentaarid (vt. näidet):
  1. Kontrollige, et programm kompileerub ja käivitub. Kas javac, java ja javadoc on kättesaadavad?
  1. Genereerige dokumentatsioon käsuga:
javadoc -private -author -version -encoding utf-8 -docencoding utf-8 -charset utf-8 Kellad.java
  1. Vaadake seda dokumentatsiooni veebilehitsejaga (alustades failist index.html). Kui on täitmata lahtreid, siis täitke need sobivate javadoc-kommentaaride lisamisega lähteteksti ja genereerige dokumentatsioon uuesti.  Kui olete tulemusega rahul, siis näidake seda juhendajale.
Siiani peaksid kõik tunnis jõudma, koodistiili analüüsi võite teha iseseisva tööna.

Java süntaks võimaldab kirja panna  igati korrektseid programme, mis paraku võivad olla inimesele täiesti loetamatud. Et kiiremini ja paremini aru saada võõrast koodist, on programmeerijad kokku leppinud järgida teatud lisakokkuleppeid, mis moodustavad nn. koodistiili. Koodistiili juures on osa reegleid, mis ei sõltu programmeerimiskeelest, teine osa on keelespetsiifilised. Üldiste reeglite hulka kuulub näiteks nõue valida muutujate nimed nii, et need peegeldaksid muutujate otstarvet, samuti nõue programmi teksti "treppida", jpt. Java-spetsiifiline reegel on aga näiteks nõue kirjutada klasside ja liideste nimed suure algustähega, muutujate ja meetodite nimed väikese algustähega. Koodistiil võib olla firmasisene (sest reeglina loevad koodi siiski sama firma töötajad), samas on ka hulk üldkehtivaid häid soovitusi.
Oskus lugeda võõrast koodi ning sellest aru saada aitab loodetavasti kaasa hea koodistiili järgimisele ka enda programmides.

Lugege läbi soovitused Java koodistiili kohta üliõpilastöödes.
Tutvuge Oracle Java koodistiiliga (pdf siin) ja Google koodistiiliga, vt. ka seda.

Analüüsige seni enda poolt kirjutatud programme: kas te järgite mingit koodistiili, mille poolest see erineb siin väljapakutud stiilist?
Võtke üks paraja pikkusega enda poolt kirjutatud programm ning vormistage see ümber, järgides täpselt ülevalpool toodud koodistiili.

Edasijõudnutele, kes kasutavad Eclipse IDEt: defineerige Eclipse toimetis koodistiil nii, et see sarnaneks võimalikult palju ülaltoodud üliõpilastööde stiiliga.
Jaanus Pöial