Kommentaar (programmeerimine)

See artikkel räägib programmeerimisel kasutatavatest kommentaaridest; selgitava märkuse kohta vaata artiklist Kommentaar

---

Illustratsioon Java lähtekoodist. Eelkommentaarid on punased, ridadevahelised kommentaarid rohelised ja programmi kood on sinine.

Kommentaar on programmeerimises arvutiprogrammi lähtekoodi osa, mis sisaldab inimloetavaid märkmeid.^[1] Need märkmed võivad olla olulised programmeerijale, kuid kompilaatorid ja interpretaatorid üldjuhul eiravad neid. Kommentaaride vormistamise reeglid sõltuvad programmeerimiskeelest.

Siin käsitletakse nii programmeerimiskeelte, märgistuskeelte, konfiguratsioonifailide kui ka muid sarnases kontekstis ilmuvaid kommentaare eristamatult, kuna nende põhimõte on sama.^[2][3]

Kommentaare saab kasutada mitmeti: alates koodi varustamisest selgitustega kuni välise dokumentatsiooni tekitamiseni. Kommentaare kasutatakse ka lähtekoodi haldussüsteemide ja teiste väliste programmeerimistööriistade integreerimiseks koodi.

Ülevaade

Kommentaarid tuleb märkida nii, et kompilaator või interpretaator nad sellistena ära tunneb. Kommentaarid esinevad koodis tavaliselt kas ploki- või reakommentaaridena ^[4].

Plokikommentaarid eraldavad koodi sees piirkonna, mis võib ulatuda üle mitme rea. See piirkond määratakse alguse- ja lõputähisega. Mõni programmeerimiskeel lubab kommentaare rekursiivselt üksteise sisse paigutada (näiteks MATLAB), kuid mõnes (näiteks Java) on see keelatud.^[5][6][7]

Reakommentaar algab kas algustähisega või mingist kindlast positsioonist. Reakommentaaril lõputähist ei ole, sest selleks on rea lõpp. Mõnes programmeerimiskeeles on olemas mõlemad kommentaariliigid, muidugi erinevate tähistega. Näiteks C++-is on plokikommentaari tähisteks /* ja */, reakommentaari algustähis on //. Mõnes keeles on ainult üht sorti kommentaare, näiteks Ada kommentaarid algavad tähisega -- ja kulgevad rea lõpuni, seal plokikommentaare pole.^[7]

Mõnes interpreteeritavas keeles, näiteks Prologis, kommentaarid formaalselt puuduvad. Nendes saab kirjutada alamprogrammi, mida kunagi välja ei kutsuta, ja selle kehasse kirjutada vajalikud märkused.

Kommentaaride kasutamine

Kuidas on kõige parem kommentaare kasutada, on vaidlusalune teema ^[8]. Inimesed pakuvad erinevaid ja vahel vastuolulisi ideid ^[9].

Kuna kommentaarid on sisu suhtes paindlikud, siis võib nende abil koodi lisada igasugust teavet, sealhulgas kasutut. Selle vältimiseks nõuab enamik tarkvaraarendajaid ja -analüütikuid kommenteerimise hea tava või koolkonna järgimist. Milles hea tava või koolkond seisneb, on suuresti kokkuleppe küsimus. Laias laastus on igas tarkvaraettevõttes oma stiil.

Koodi kirjeldamine

Kommentaare võib kasutada kokkuvõtte tegemiseks või programmeerija kavatsuste selgitamiseks. Selle mõtteviisi esindajate arvates on parim viis kommentaare kirjutada lihtsas keeles; vajadus asju üle selgitada võib olla märk, et kood on liiga keeruline ja tuleks ümber kirjutada.

"Ära kommenteeri halba koodi – kirjuta see ümber." ^[10]

"Head kommentaarid ei korda koodi ega selgita seda. Nad selgitavad selle eesmärki. Kommentaarid peaksid selgitama sinu kavatsusi paremini kui kood ise." ^[11]

Kommentaare saab kasutada ka selgitamaks, miks mingi osa koodist ei sobi sinna, kus ta on. Seda kasutatakse projektide juures, kus on vähe aega arendustegevuseks või kui parandatakse vigu. Näiteks:

' Second variable dim because of server errors produced when reuse form data.
' No documentation available on server behavior issue, so just coding around it.
 vtx = server.mappath("local settings")

Algoritmi kirjeldus

Mõnikord sisaldab programm uudseid või märkimisväärseid lahendusi mingile probleemile. Sellisel juhul võivad kommentaarid sisaldada selgitusi kasutatud meetodi kohta. Need selgitused võivad sisaldada diagramme ja matemaatilisi tõestusi. Seda võib lugeda koodi selgitamiseks, mitte koodi eesmärgi kirjeldamiseks. Inimesed, kes tegelevad koodibaasi hooldamisega, võivad selliseid selgitusi ülitähtsateks pidada, eriti kui lahendatakse väga erilisi probleeme või kui kasutatakse haruldasi lihtsustusi, konstruktsioone või ülesandeid.^[12]

Näiteks võib programmeerija lisada kommentaari, selgitamaks, miks kasutati vahelepanemisega sortimist kiirsortimise asemel, kuigi esimene on teoreetiliselt aeglasem kui teine:

  list = [f (b), f (b), f (c), f (d), f (a), ...];
  // Need a stable sort. Besides, the performance really does not matter.
  insertion_sort (list);

Andmete lisamine koodi

ASCII-kunsti abil saab koodi sisestada ja kommentaarina vormistada logosid, diagramme, vooskeeme ja muud ^[13]. Autoriõiguste kohta käivad hoiatused võivad samuti lähtekoodis kommentaaridena olla. Binaarandmed võivad esineda koodis kommentaarina, kuid see on haruldane ja tavaliselt paigutatakse need eraldi faili.

Järgmine koodilõik on lihtne ASCII diagramm, mis kujutab protsessivoogu süsteemi haldusskriptis Windows Script File, mis jookseb Windows Script Hostis. Kuigi lõik, kus kood asub, näib kommentaarina, ilmub diagramm hoopis XML CDATA lõigus, mis erineb kommentaarist, kuid võib täita samu ülesandeid ^[14]. Mõnikord seisneb kommentaaride ja muude süntaksielementide vahe programmeerimis- ja märgistuskeeltes ainult nüanssides. Niederst viitab ühele sellisele juhtumile, öeldes: "Kahjuks võib XML tarkvara kommentaare ebaoluliseks infoks pidada ja need dokumendist kustutada enne selle töötlemist. Selle probleemi vältimiseks tuleb kasutada XML CDATA lõiku." ^[14]

 <!-- begin: wsf_resource_nodes -->
 <resource id="ProcessDiagram000">
 <![CDATA[
  HostApp (Main_process)
     |
     V
 script.wsf (app_cmd) --> ClientApp (async_run, batch_process)
                 |
                 |
                 V
          mru.ini (mru_history)   
 ]]>
 </resource>

Kuigi sarnase diagrammi saab ka kommentaarina lähtekoodi lisada, on siin näidatud, et programmeerija võib allikaid ka muul viisil lähtekoodi kaasata.^[14]

Silumine

On üsna tavaline, et programmeerija mingi koodiosa välja kommenteerib, et see programmis ei käivituks. Seda tehakse laialdaselt programmi testimise ajal. Sealjuures tuleb olla ettevaatlik, sest väljakommenteeritav programmiosa võib ise kommentaare sisaldada, aga kõik keeled ei luba üht kommentaari teise sisse paigutada.

  if (opt.equals ("e"))
    opt_enabled = true;
  /*
   if (opt.equals ("d"))
    opt_debug = true;
  // */
  //*
  if (opt.equals ("v"))
     opt_verbose = true;
  // */

Selles programmilõigus on programmeerija silumisvaliku keelanud. Üksik kaldkriips esimese eraldaja ees on lüliti, mis lubab või keelab plokikommentaari.

Automaatne dokumentatsiooni tekitamine

Arendustööriistad salvestavad mõnikord dokumentatsiooni ja meta-andmeid kommentaarides ^[15]. Need võivad sisaldada sisestuspositsiooni automaatseks lisamiseks päisefaili ja käske faili süntaksi esiletõstmiseks ^[16] või faili versiooni numbrit ^[17]. Selliseid funktsionaalse kontrolli kommentaare nimetatakse vahel annotatsioonideks. Dokumentatsiooni lähtekoodis hoidmine on üks viis, kuidas dokumenteerimist lihtsustada ja dokumentatsiooni värskena hoida, kuna dokumentatsioon uueneb siis koos koodiga ^[18].

Dokumentatsiooni generaatorite näited on programm javadoc, mis on mõeldud Java jaoks, Ddoc, mis on mõeldud D jaoks, doxygen, mida kasutatakse C++, C, Java ja IDLi jaoks, ning PHPdoc PHP jaoks.

C# ja Visual Basic kasutavad omadust XML Comments, mida loetakse IntelliSense'i abil kompileeritud .NET assemblerist.^[19]

Vaated

Selle kohta, kuidas kommentaare lähtekoodis kasutada, on palju vaateid ja arvamusi ^[20][21]. Osa neist on mitteametlikud ja põhinevad isiklikel eelistustel, teised on avaldatud ametlike juhistena ^[22].

Vajadus kommentaaride järele

Asjatundjatel on väga erinev nägemus sellest, millal ja kuidas kommentaare koodi lisada.^[10][23][24]

Puuduvad kommentaarid võivad muuta koodi mõistmise raskeks, aga kommentaarid võivad segada või olla lausa kahjulikud, kui nad on vananenud, valed või lihtsalt arusaamatud. Mõni asjatundja leiab, et kommentaare tuleb kasutada minimaalselt, sest kood peab iseenesest arusaadav olema ^[10]. Teised jälle leiavad, et kommentaare tuleb kasutada laialdaselt. On tavaline, et üle poole koodist moodustavad kommentaarid ^[25][26].

Nende kahe vaate vahele jääb veel arvamus, et kommentaarid pole iseenesest kasulikud ega kahjulikud, loeb vaid nende täpsus ja koodiga kaasas käimine. Seda eeldusel, et kommentaarid pole üleliigsed, liiga mahukad, keerulised majandada ega muul viisil segavad.^[23][27]

Detailsus

Olenevalt lugejatest ja muudest asjaoludest võib koodi detailsus oluliselt erineda.

Näiteks sobiks järgmine Java kommentaar algajate programmeerijate õpetamisel:

    String s = "Wikipedia"; /* Annab väärtuse "Wikipedia" muutujale s. */

Selline detailsus pole aga kohane reaalse programmi koodis ega muul juhul, kus tegemist on kogenud programmeerijatega. Sellised algelised kirjeldused on vastuolus soovitusega "Head kommentaarid ... selgitavad kavatsust".^[11]

Ebaviisakad kommentaarid

Tuleb ette, et kommentaaride abil maandatakse stressi või räägitakse pahasti arendusvahenditest, konkurentidest, tööandjatest, töötingimustest ja isegi koodi enda kvaliteedist. Paljud asjatundjad peavad seda täiesti kohatuks, eriti kui koodi võib tulevikus vaadata keegi peale algse kommenteerija enda.^[28]

Selliseid juhtumeid võib näha internetis lehekülgedel, mis otsivad lähtekoodist roppusi.^[29]

Vähemalt sama ebaviisakas on kirjutada segane ja arusaadamatu programmilõik ning kommenteerida seda lausega: "Eks te proovige ära arvata, mida ma siin teen!"

Kommentaaride turvalisus

Veebidisainis esineb kommentaaridega seotud turvaprobleeme. Pole tavatu, et HTML-i kommentaarid on rakenduse igale kasutajale tavalise tekstina nähtavad. Lõigud koodist, mis on HTML-i mallides välja kommenteeritud, on seetõttu turvarisk.^[30]

Stiil

Kommentaaride kirjutamiseks lähtekoodi on palju stiile. Suurtes projektides, milles tegutseb palju programmeerijaid, lepitakse kommentaaride kasutamise stiil alguses kokku või kujuneb see töö käigus ise. Üldiselt eelistavad programmeerijad stiile, mis on järjepidevad, ei sega, on lihtsad täiendada ega lähe kergesti katki.^[31]

Järgmised C-keele kommentaarid demonstreerivad, kuidas kahes stiilis anda edasi sama teavet.

 /* 
      See on kommentaari keha.
      Esimene variant
 */

 /***************************\
 *                           *
 * See on kommentaari keha.  *
 * Teine variant             *
 *                           *
 \***************************/

Isiklik eelistus, programmeerimiskeskkond ja muud asjaolud mõjutavad seda, millist kommenteerimise stiili kasutatakse. Näiteks võib teine variant olla vastumeelne programmeerijale, kes ei kasuta redaktorit, mis kommentaari automaatselt vormindab ja joondab.

Tarkvarakonsultant ja tehnoloogia asjatundja Allen Holub propageerib kommentaaride joondamist vasaku serva järgi.^[32][33]

 /* Seda stiili soovitab Holub C and C++ jaoks.
  * See on kirjas teoses "''Enough Rope''", reeglis 29.
  */

 /* See on teine moodus seda teha, samuti C-s.
 ** Niimoodi on kergem kirjutada redaktorites, mis automaatselt ei alusta kommentaari
 ** ülejäänud ridu ühe positsiooni võrra suurema taandega kui kommentaari esimest rida.
 ** Ka seda kasutatakse Holubi raamatus, reeglis 31.
 */

Kommentaarid rea lõpus

Sel juhul eiratakse kogu teksti pärast ASCII märke // kuni rea lõpuni.

 // begin: Variation Three.
 // -------------------------
 // This is the comment body.
 // -------------------------

Eri koodiosade jaoks võib valida eri kommenteerimisstiili. Kui süntaks toetab nii reakommentaare kui plokikommentaare, siis üks võimalus on kasutada reakommentaare ääremärkusteks (toimetamine, struktureerimine) ja plokikommentaare üldisematel teemadel (funktsioonid, klassid, moodulid ja failid).

Märgendid

Kommentaarides kasutatakse märgendeid, et tähistada probleeme. Sellised märgendid on tavaliselt süntaksis esile tõstetud ja neid saab leida tavaliste programmeerimistööriistade, näiteks UNIX-i grepiga. Näited:

• FIXME – koodi märkimiseks, mis võib vajada ülevaatamist või ümbertegemist
• NOTE – dokumenteerimaks koodi sisu ja hoiatuseks probleemide eest
• TODO – märkimaks plaanitavaid muudatusi
• XXX – hoiatamaks programmeerijaid puudustega või vigase koodi eest.

Märgendid võivad pika aja peale kuhjuma hakata, seega on soovitav nende juurde märkida tegemise aeg ja autor, et järjepidamist lihtsustada.^[34]

Näited

Kommentaaride kirjutamise reeglid erinevad keeleti oluliselt. Paljudes programmeerimiskeeltes on sellele keelele ainuomaseid kommenteerimismooduseid.

Klassikaline BASIC

See BASIC-koodi lõik on täiesti töökorras programm, milles kommentaarid kirjeldavad programmi tööd. Sellised kommentaarid on mõeldud eelkõige algajale programmeerijale.

10 REM See BASICu programm näitab, kuidas kasutada PRINT- ja GOTO-lauset.
15 REM See täidab ekraani sõnaga "VIKIPEEDIA".
20 PRINT "VIKIPEEDIA"
30 GOTO 20

Selle programmi käivitamisel trükitakse ekraanile lõputult sõna "VIKIPEEDIA" (jutumärkideta).

C

See C koodi lõik näitab sissejuhatava plokikommentaari kasutamist, et kirjeldada tingimuslause eesmärki. Kommentaar sisaldab peamisi termineid ja põhimõtteid ning programmeerija lühikest signatuuri.

 /*
  * Check if we are over our maximum process limit, but be sure to
  * exclude root. This is needed to make it possible for login and
  * friends to set the per-user process limit to something lower
  * than the amount of processes root is running. -- Rik
  */
 if (atomic_read(&p->user->processes) >= p->rlim[RLIMIT_NPROC].rlim_cur
     && !capable(CAP_SYS_ADMIN) && !capable(CAP_SYS_RESOURCE))
     goto bad_fork_free;

See näide on Tfork.c failist Linuxi tuuma lähtekoodis.

ColdFusion

ColdFusion kasutab sarnaseid kommentaare nagu HTML/XML, kuid kahe kriipsu asemel on selle eraldajates kolm kriipsu. ColdFusioni mootor filtreerib need kommentaarid välja ja neid ei väljastata.

 <!--- See väljastab brauserisse sõnad "Tere, maailm!". --->
 <cfoutput>
   Tere, maailm!<br />
 </cfoutput>

Fortran 90

See FORTRANi koodi lõik näitab, kuidas kommentaare selles keeles kasutatakse.

!* * * * * * * * * * * * * * * * * * * * * * * * * * * * * * *
!* Kõik tähemärgid pärast hüüumärki loetakse kommentaariks.  *
!* * * * * * * * * * * * * * * * * * * * * * * * * * * * * * *
       PRINT "WIKIPEDIA" ! Fortran 90 võttis kasutusele reakommentaarid.
       END

Java

See Java koodi lõik näitab plokikommentaari kasutamist, et kirjeldada setToolTipText meetodit. Selle vormindus vastab Sun Microsystemsi Javadoci standardile ja on mõeldud javadoci protsessoriga lugemiseks.

 /**
  * Registers the text to display in a tool tip. The text 
  * displays when the cursor lingers over the component.
  *
  * @param text  the string to display. If the text is null, 
  *              the tool tip is turned off for this component.
  */
 public void setToolTipText(String text) {

Perl

Reakommentaar Perlis ja mitmes teises skriptikeeles algab trellidega (#). Kommentaar alguses nimega shebang ütleb süsteemile, millist interpretaatorit kasutada.

#!/usr/bin/perl
my $s = "Vikipeedia"; # Annab muutujale s väärtuseks "Vikipeedia".
print $s . "\n";      # Lisab uue rea pärast väljastamist kestades (shells), mis seda automaatselt ei tee.

PHP

Kommentaarid PHPs võivad olla kas C++ stiilis (nii rea- kui plokikommentaarid) või Perli stiilis. PHPDoc on javadocilt üle võetud stiil ja üsna levinud viis PHP koodi dokumenteerimiseks.

Python

Kommentaarid Pythonis algavad trellidega "#". Et operatsioonisüsteem teaks, millist interpretaatorit kasutada, algavad Pythoni programmid märkidega #!.

#!/usr/bin/python
# See programm trükib ekraanile "Tere, maailm!". 
print "Tere, maailm!"

Ruby

Üherealised kommentaarid Rubys algavad trellidega "#":

See ei ole kommentaar
#See on kommentaar
See ei ole kommentaar

Mitmerealised kommentaarid lähevad reserveeritud sõnade "begin" ja "end" vahele:

See ei ole kommentaar
=begin
Siin vahel
ignoreeritakse kõike :)
=end
See ei ole kommentaar

SQL

Transact-SQLi süntaks toetab kaht tüüpi kommentaare ^[35]. Plokikommentaar langeb ühte C++ ja Java plokikommentaaridega.

/*
See on kommentaari 1. rida
See on kommentaari 2. rida
*/
SELECT COUNT(*)
       FROM Authors

Teine kommenteerimise võimalus Transact-SQL-is on reakommentaar, mis langeb ühte Ada kommentaaridega:

-- See on üherealine kommentaar,
-- millele järgneb teine rida.
SELECT COUNT(*) 
       FROM Authors
       WHERE Authors.name = 'Smith'; -- Märkus: me tahame ainult Smithi
                                     -- See kommentaar ilmub pärast SQL koodi

Viited

1. Lähtekoodi võib jagada programmikoodiks, mida loeb arvuti, ja kommentaarideks, mida loeb inimene. Penny Grubb, Armstrong Takang (2003). Software Maintenance: Concepts and Practice. World Scientific. Lk 7, 120–121. ISBN 981238426X.
2. Ganguli, Madhushree (2002). Making Use of Jsp. New York: Wiley. ISBN 0471219746.
3. Hewitt, Eben (2003). Java for Coldfusion Developers. Upper Saddle River: Pearson Education. ISBN 0130461806.
4. Dixit, J.B. (2003). Computer Fundamentals and Programming in C. Laxmi Publications. ISBN 8170088828.
5. Higham, Desmond (2005). MATLAB Guide. SIAM. ISBN 0898715784.
6. Vermeulen, Al (2000). The Elements of Java Style. Cambridge University Press. ISBN 0521777682.
7. "Using the right comment in Java". Vaadatud 24. juuli 2007.
8. W. R., Dietrich (2003). Applied Pattern Recognition: Algorithms and Implementation in C++. Springer. ISBN 3528355581., lk. 66.
9. Keyes, Jessica (2003). Software Engineering Handbook. CRC Press. ISBN 0849314798. ("Science of Documentation"), lk. 256.
10. "The Elements of Programming Style", Brian Kernighan & P. J. Plauger
11. "Code Complete", Steve McConnell
12. Spinellis, Diomidis (2003). Code reading: The Open Source Perspective. Addison-Wesley. ISBN 0201799405.
13. "CodePlotter 1.6 – Add and edit diagrams in your code with this 'Visio-like' tool". Vaadatud 24. juuli 2007.
14. Niederst, Jennifer (2006). Web Design in a Nutshell: A Desktop Quick Reference. O'Reilly. ISBN 0596009879.
15. Wynne-Powell, Rod (2008). Mac Os X for Photographers: Optimized Image Workflow for the Mac User. Oxford: Focal Press. ISBN 0240520270., lk 243
16. Lamb, Linda (1998). Learning the VI Editor. Sebastopol: O'Reilly & Associates. ISBN 1565924266.
17. Berlin, Daniel (2006). Practical Subversion, Second Edition. Berkeley: APress. ISBN 1590597532., lk 168
18. Ambler, Scott (2004). The Object Primer: Agile Model-Driven Development with UML 2.0. Cambridge University Press. ISBN 1397805218.
19. Murach. C# 2005. Lk 56.
20. Goodliffe, Pete (2006). Code Craft. San Francisco: No Starch Press. ISBN 1593271190.
21. Smith, T. (1991). Intermediate Programming Principles and Techniques Using Pascal. Belmont: West Pub. Co. ISBN 0314663142.
22. Koletzke, Peter (2000). Oracle Developer Advanced Forms & Reports. Berkeley: Osborne/McGraw-Hill. ISBN 0072120487., lk 65
23. Your, Edward (2007). Techniques of Program Structure and Design. University of Michigan. 013901702X.
24. "Worst Practice – Bad Comments". Vaadatud 24. juuli 2007.
25. Morelli, Ralph (2006). Java, Java, Java: object-oriented problem solving. Prentice Hall College. ISBN 0131474340.
26. "How to Write Doc Comments for the Javadoc Tool". Vaadatud 24. juuli 2007. JavaDoci juhised ütlevad, et kommentaarid on selle platvormi jaoks olulised. Lisaks on sobiv detailsus suhteliselt hästi määratletud.
27. Dewhurst, Stephen C (2002). C++ Gotchas: Avoiding Common Problems in Coding and Design. Addison-Wesley Professional. ISBN 0321125185.
28. Doar, Matthew B. (2005). Practical Development Environments. O'Reilly. ISBN 0596007965.
29. Linux Swear Count, Google Code Search
30. Andress, Mandy (2003). Surviving Security: How to Integrate People, Process, and Technology. CRC Press. ISBN 0849320429.
31. "Coding Style". Originaali arhiivikoopia seisuga 8. august 2007. Vaadatud 24. juuli 2007.
32. "Allen Holub". Originaali arhiivikoopia seisuga 20. juuli 2007. Vaadatud 24. juuli 2007.
33. Allen Holub, "Enough Rope to Shoot Yourself in the Foot", ISBN 0-07-029689-8, 1995, McGraw-Hill
34. "TODO or not TODO". Vaadatud 8. veebruar 2009.
35. Talmage, Ronald R. (1999). Microsoft SQL Server 7. Prima Publishing. ISBN 0761513892.

Välislingid

• How to Write Comments Denis Krukovsky (inglise keeles)
• Source Code Documentation as a Live User Manual PTLogica (inglise keeles)
• How to Write Comments for the Javadoc Tool (inglise keeles)
• Doxygen Dokumenteerimissüsteem C, C++-i, JAVA, Objecitve-C, Python'i, IDL'i ja mõningal määral PHP, C# ja D jaoks. (inglise keeles)