U ovoj lekciji obrađivaćemo:

  • Vrste komentara
  • Preporuke za efikasno komentarisanje koda
  • Tenike komentarisanja koda

Komentarisnje programa ima veliku važnost u razvoju kvalitetnog softvera. Pre prelaska na preporuke za samo komentarisanje koda, pogledajmo nekoliko primera.

Primer 1


// 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.

Primer 2


// 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.

Primer 3


// 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.

Vrste komentara

Komentari mogu da se klasifikuju u šest kategorija:

  1. Ponavljanje koda - Ova vrsta komentara precizira drugim rečima šta kod predstavlja. Ne pruža čitaocu dodatne informacije.
  2. Objašnjenje koda - Ovi komentari se tipično koriste da objasne komplikovane, zamršene ili osetljive linije koda. Tada su veoma korisni, ali pre svega zato što je kod zbunjujući ili konfuzan. Ako je kod toliko komplikovan da je potrebno objašnjenje, skoro je uvek bolje poboljšati kod nego dodavati komentar. Treba učiniti kod jasnijim, a potom koristiti komentare za pregled navedene u nastavku.
  3. Markeri u kodu - Markeri su komentari koji nisu namenjeni da ostanu u kodu. Predstavljaju poruku programera da rad još nije završen. Često se i stavljaju pod posebnim karakterima da bi se lakše našli prilikom pretrage.
  4. Pregled koda - Ova vrsta komentara u jednoj ili dve rečenice opisuje nekoliko linija koda. Korisni su za one koji nisu autori koda.
  5. Opis namene koda - Komenatri opisa namene objašnjavaju svrhu sekcije koda. Nekada se poistovećuju sa pregledima koda. Navode se u formi problema, nego u formi rešenja. Primer: dohvatanje podataka o zaposlenom.
  6. Komentari nevezani za sam kod - Pojedine vrste komentara se takođe navode u izvornom kodu, i ako nisu vezani za sam kod, kao što su npr. copyright informacije, broj verzije, online reference  i sl.

Tri vrste komentara koji su prihvatljivi za kompletiran kod su 4, 5, 6.

Efikasno komentarisanje

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.

C++ primer komentarisanja koji je težak za održavanje


/**********************************************************************

 * class:  GigaTron (GIGATRON.CPP)                                    *
 *                                                                    * 
 * author: Dwight K. Coder                                            *
 * date:   July 4, 2014                                               *
 *                                                                    * 
 * Routines to control the twenty-first century's code evaluation     *
 * tool. The entry point to these routines is the EvaluateCode()      *
 * routine at the bottom of this file.                                *

**********************************************************************/

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:

C++ primer komentarisanja koji je jednostavan za održavanje


/**********************************************************************

  class:  GigaTron (GIGATRON.CPP)
  author: Dwight K. Coder
  date: July 4, 2014

  Routines to control the twenty-first century's code evaluation
  tool. The entry point to these routines is the EvaluateCode()
  routine at the bottom of this file.

**********************************************************************/

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.

Tehnike komentarisanja

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.


Anegdota - izbegavati zagonetne komentare

Postoji jedna interesantna anegdota o autor jednog programa koji je koristio krajnje neobičan komentar u svom programu. Posle izvesnog vremena, autor je napustio kompaniju, a programer koji je održavao program pozvan da reši problem koji se u međuvremenu pojavio. Pošto autor više nije bio dostupan, oslonio se na dokumentaciju programa, ali je naišao samo na jedan komentar tipa:

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:

  1. S. McConnell, Code Complete: A Practical  Handbook of Software Construction, Microsoft Press, second ed., 2004.
  2. Card, David N. , Victor E. Church , and William W. Agresti . "An Empirical Study of Software Design Practices." IEEE Transactions on Software Engineering SE-12, 1986.
Dodaj komentar Sviđa mi se - (0) Ne sviđa mi se - (0)    

  • Komentarisanje programa 1
  • Komentarisanje programa 2
  • Komentarisanje programa 3