Koodimisstiil

Koodi kommenteerimine

Kommenteerimine on vajalik, et hiljem kergemini leida koodis soovitud kohti paranduste või muudatuste tegemiseks ning ka teistele, kes peavad hiljem Teie kirjutatud koodi lugema või sellega töötama. Keskeltläbi peaks iga 10 koodirea kohta olema vähemalt 1 kommentaar, mis selgitab programmi tööd.

Koodi kommenteerimiseks on mitmeid võimalusi:

  • Eraldi real olev kommentaar
  • Samal real olev kommentaar
  • Mitmerealised kommentaarid (vt Faili päis)
  • Kommentaari algustähise ja sisu vahel on tühik
  • Kaldriipsude järel olevat teksti kuni reavahetuseni võetakse kui kommentaari
  • Samal real olevate kommentaaride puhul tuleks jälgida nende pikkust. Pikemate kommentaaride korral tasub kasutada kas eraldi real olevaid kommentaare või mitmerealisi kommentaare.


Täiendavalt on kommentaarid vaja ka lisada enda loodud funktsioonidele  ja failide päisesse ning selle jaoks kasutatakse enamasti mitmerealisi kommentaare.

Faili päis

Kõikide .c ja .h failide päisesse tuleks lisada koodifaili nimi, autor,  muutmise kuupäev (või versioon, kui kasutatakse versioonihaldust) ja failis sisalduva koodi eesmärk.  Sageli on kombeks ka lisada URL või e-post.

Faili päise puhul kasutatakse kommenteerimise viisi, kus kommentaar algab märkidega /* ja lõpeb märkidega */. Kõik vahepealne loetakse kommentaariks.

Arvutused

  •  Kõik toimingud, mis kasutavad vähemalt 2 operandi tuleb eraldada tühikutega
  • Unaarsed operaatorid kirjutatakse kokku operandiga. Näiteks  !holiday ehk NOT holiday, ~a ehk INV a (bitikaupa inverteerimine), k– (dekrementeerimine)
Näide halvast stiilist:

Muutujate deklareerimine ja initsialiseerimine

  • Muutujate nimed peaksid kirjeldama nende sisu
  • Nimetamisel kasutame kaameliküüru meetodit – st ühesõnalised muutujad algavad väikese tähega ja mitmesõnaliste puhul on järgnevad sõnad suure algustähega.
  • Viidad ja tavalised muutujad deklareeritakse erinevatel ridadel
  • Ühest tüübist võib deklareerida mitut muutujat, eraldades need koma ja tühikuga, kuid sellisel juhul ei tohiks neid algväärtustada samal real.
  • Globaalmuutujate kasutamist tuleks vältida
Näide halvast stiilist:

#define direktiivid

  • Nimetus kirjutatakse suurtähtedes
  • Üks kasutusvaldkondadest on maagiliste numbrite vältimine koodis
  • Mitmesõnalised nimed kirjutatakse altkriipsuga

Treppimine

  • Treppimine on vajalik koodi loetavuse parandamiseks, seda nii endale hiljem töö jätkamiseks või parandamiseks, kui ka teistele, kes seda koodi peavad töös kasutama, lugema, parandama või edasi arendama.
  • Treppimine 1 võrra tähendab teksti alguse nihutamist 4 tühiku võrra edasi. Tavaliselt saab selleks kasutada tabulaatorit.
  • Enamikel juhtudel võib jälgida reeglit, et loogeliste sulgude alguse järel trepitakse kõik selle sisu kuni konkreetse sulupaari lõpuni 1 võrra.
  • Treppimine annab suure loetavuse eelise olukordades, kus mitmeid tsükleid, tingimus jms kasutatakse üksteise sees. Sedasi on arendajal parem visuaalne ülevaade kus üks plokk algab võib lõppeb. Samuti aitab vältida vigu sulgude panekul.
  • Soovitus: trepi jooksvalt koodi kirjutades, mitte ära ürita hiljem parandada tehtud vigu. Enamik redaktorid trepivad automaatselt kasutaja eest, kui trükkida sisse loogeline sulg ‘{‘ ning seejärel vajutada ‘enter’ klahvi.
  • Soovitus:  Lisaks algavale loogelisele sulule sisesta ka kohe lõppev loogeline sulg – sedasi ei unune see ära ja väldid hilisemaid probleeme.

Näide halvast stiilist:

Koodirea pikkus ja poolitamine

Üks koodirida ei tohiks ületada 80 tähemärki. See aitab nii koodi loetavuse kui ka ühilduvuse poolest teiste platvormidega.

Saamaks aimu millal on vaja rida poolitada on redaktorites olemas visuaalsed abivahendid.

Geany: Edit -> Preferences -> Editor -> Display
Vali Long line marker: Enabled ja column: 80

Code::Blocks: Settings -> Editor -> Margins and caret
Vali right margin hint kas visible line või highlight ja column: 80

Näite raames on kasutatud lühemat rida kui 80 tähemärki. Rea poolitamisel pole vaja ühtegi täiendavat sümbolit kasutada. Küll aga tuleks jälgida, et rida poolitades tuleks sama lause alla kuuluv tekst treppida 1 tabi võrra. Järgmine lause kirjutatakse jälle algselt kauguselt.

Näide halvast stiilist

Tingimuslaused

  • Loogelised sulud algavad ja lõppevad eraldi real
  • Loogeliste sulgude sisu on 1 võrra edasi trepitud (4 tühikut)
  • if järel on 1 tühik.
  • Üldistatult on tühik kõikide lausete järel enne ümarsulge, millele järgneb loogeliste sulgude sees olev täidetav kood
    See ei kehti main() ja enda loodud funktsioonide korral!
  • Aritmeetilised ja võrdlusoperaatorid (=, +, ==, <=, <, >  jne) on ümbritsetud tühikuga.  Küll aga ei laiene see unaarsetele operatsioonidele.

Switch lause

  • switch järel on tühik (meenuta üldistust)
  • case ja selle väärtuse vahel on tühik
  • switchi sisu on trepitud 1 võrra
  • kõigi case’ide sisu on veelkorra trepitud

Tsüklid:

  • While ja for järel on tühik (meenuta üldistust)
  • Loogelised algavad ja lõppevad ühel tasemel, eraldiseisval real
  • Loogeliste sulgude sisu on 1 võrra trepitud
  • Märka kindlasti ka for lauses semikoolonite järel ja operaatorite ees ja järel olevaid tühikuid.

 Funktsioonid

 main() funktisoon
või
  • Esimest kirjapilti kasutatakse olukorras, kus programmile ei soovita kaasa anda täiendavaid parameetreid käivitamise hetkel käsurealt.
  • Teist kirjapilti võib kasutada ainult juhul, kui programmi käivitamisel soovitakse käsuribalt anda kaasa täiendavaid parameetreid
 Enda loodud funktsioonid
  • Funktsiooni nimest peaks olema võimalik välja lugeda selle eesmärk
  • Funktsioonide nimetamisel kasutame KaameliKüüruMeetodit, kus kõik sõnad kirjutatakse kokku ning algava suure tähega. Sedasi saame eristada neid kenasti muutujatest, makrotest jt.
  • Enda loodud funktsioonidel peab olema prototüüp, mis paikneb kas samas failis enne main() funktsiooni või eraldi päisefailis.
Funktsiooni kommentaarid
  • Funktsioonile peab alati eelnema kommentaar, mis annab selge arusaama funktsiooni eesmärgist ning kuidas see töötab.
  • Väga lihtsate funktsioonide korral võib kasutada lühendatud kommentaari kuju, kuid pigem on põhjalikkus siin voorus.
Standartne funktsiooni kommentaari kuju
  • Funktsiooni parameetrid – nende nimed, andmetüübid ja väärtuse tähenduslikkus antud funktsioonis. Kui eksisteerivad, siis ka piirangud (eeltingimused) väärtustele
  • Funktsiooni poolt tagastatav väärtus – andmetüüp ja selle tähenduslikkus
  • Kirjeldus – sisaldab funktsiooni eesmärki, tööpõhimõtteid, piiranguid. Kui funktsiooni käigus muudetakse andmeid, mis pole funktsioonile lokaalsed, siis see tuleb samuti kirja panna (nt massiivid)
Lihtne kommentaari kuju
  • Antud kuju tohib kasutada vaid väga lihtsate ja elementaarsete funktsioonide puhul.
Funktsiooni prototüüp
  • Enda loodud funktsioonil peab olema alati loodud prototüüp.
  • Nimetamisreeglid pärinevad juba varasemalt olnud eeskirjadest – kuidas nimetada muutujaid ja kuidas nimetada enda loodud funktsiooni.
  • Funktsiooni parameetrite juures märgime alati lisaks tüübile ka nimetuse.
  • Funktsiooni prototüübid paiknevad koodis kas eraldiseisvas päisefailis (soovituslik) või enne main() funktsiooni ja pärast preprotsessori direktiivne (#define, #include)