U ovoj lekciji obrađivaćemo:
Komentarisnje programa ima veliku važnost u razvoju kvalitetnog softvera. Pre prelaska na preporuke za samo komentarisanje koda, pogledajmo nekoliko primera.
// write out the sums 1..n for all n from 1 to num current = 1; previous = 0; sum = 1; for ( int i = 0; i < num; i++ ) { System.out.println( "Sum = " + sum ); sum = current + previous; previous = current; current = sum; } |
Ova rutina računa prvih num Fibonacijevih brojeva. Komentar u prvoj liniji uz ovu rutinu je pogrešan, i ako se čitalac osloni samo na njega, odvešće da na pogrešnu stranu.
// set product to "base" product = base; // loop from 2 to "num" for ( int i = 2; i <= num; i++ ) { // multiply "base" by "product" product = product * base; } System.out.println( "Product = " + product ); |
Komentar uz ovu rutinu je tačan, ali ne dodaje nikakvo novo objašnjenje.
// compute the square root of Num using the Newton-Raphson approximation r = num / 2; while ( abs( r - (num/r) ) > TOLERANCE ) { r = 0.5 * ( r + (num/r) ); } System.out.println( "r = " + r ); |
Ova rutina izračunava kvadratini koren od num. Kod nije sjajan, ali je komentar tačan.
U suštini, ove rutine pokazuju prednosti i mane unutrašnjih komentara. Prvi primer ima netačan komentar, drugi ima komentar koji prepisuje kod i nije od preterane koristi. Samo je komentar u trećem primeru dobar. Loši i siromašni komentari su gori od nepostojećih komentara.
Komentari mogu da se klasifikuju u šest kategorija:
Tri vrste komentara koji su prihvatljivi za kompletiran kod su 4, 5, 6.
Efikasno komentarisanje ne oduzima toliko vremena. Previše komentara je isto tako loše kao i kada ih je premalo. U nastavku su date preporuke za efikasno komentarisanje.
Korišćenje stilova koji se lako modifikuju. Kao ilustraciju pogledajmo sledeći primer.
* class: GigaTron (GIGATRON.CPP) * **********************************************************************/ |
Ovako napisan blok komentar izgleda lepo, čitav blok je vidljivo zaokružen, sa jasno istaknutim početkom i krajem. Ono što nije vidljivo na prvi pogled je težina održavanja, koja je komplikovana zbog zvezdica sa leve ili desne strane, koje treba ubacivati i pomerati pri modifikacijama. Sledeći primer takođe lepo izgleda, ali je jednostavniji za održavanje:
class: GigaTron (GIGATRON.CPP) Routines to control the twenty-first century's code evaluation **********************************************************************/ |
Korišćenje pseudokoda radi uštede vremena - Ukoliko se istaknu komentari pre samog pisanja koda, ostvaruju se velike uštede. Po završetku kodiranja, komentari su već tu. Na ovaj način se i iskorišćavaju sve dizajn prednosti pisanja pseudokoda na visokom nivou, pre popunjavanja na niskom nivou samog koda.
Uključivanje komentarisanja u stil rada programera - Alternativa ovom pristupu je ostavljanje komentarisanja sve do kraja projekta, što ima više nedostataka. Ostavlja se veći deo posla kao poseban veći task, umesto da se radi po malo s vremena na vreme. Takođe, komentarisanje kasnije zahteva više vremena, jer je potrebno pamtiti i setiti se svega kodiranog, umesto da se zapiše komentar kada se već radi taj deo.
Za komentarisanje postoji nekoliko različitih tehnika u zavisnosti od nivoa na koji se odnosi komentar: program, fajl, rutina, ili linija koda.
Komentarisanje individulanih linija - U dobrom kodu, potreba za komentarisanjem pojedinih linija koda je retka. Postoje dva razloga zašto linija koda treba da ima komentar: linija koda je suviše komplikovana i zahteva objašnjenje, linija koda je nekada imala grešku i potrebno je zapisati informaciju o tome.
MOV AX, 723h ; R. I. P. L. V. B. Nakon mukotrpnog rada, ipak je uspeo da otkloni grešku. Posle nekoliko meseci, programer je sreo autora na jednoj konferenciji i konačno saznao značenje komentara: "Rest in peace, Ludwig van Beethoven." Beethoven je umro 1827 (decimalno), što je 723 (hexadecimalno). To što to nema nikakve veze sa samim kodom, nije bilo bitno! |
Komentarisanje na kraju reda - Ovakvi komentari se unose u nastavku linija sa kodom. Ponekada mogu biti korisni, ali ih treba izbegavati jer unose nepreglednost u sam kod i teški su za modifikovanje i formatiranje.
Komentarisanje pasusa koda - Ovo je najčešća vrsta komentara koja se koristi u dobro dokumentovanom programu:
// swap the roots oldRoot = root[0]; root[0] = root[1]; root[1] = oldRoot; |
Ova vrsta komentara opisuje namenu koda i lako se održava.
Reference: