C-keele kommentaarid: Parimad tavad, tüübid ja kasutusjuhised

1. Sissejuhatus

Kommentaaride olulisus C keeles
C keel on väga võimas ja paindlik programmeerimiskeel, kuid isegi arendaja jaoks võib kood muutuda aja jooksul raskesti mõistetavaks. Seetõttu on “kommentaarid” väga olulised, et koodi oleks lihtsam lugeda ja mõista. Kommentaarid on märkmed, mis ei mõjuta programmi käivitamist, kuid aitavad koodi paremini mõista. Selles artiklis selgitatakse üksikasjalikult, kuidas C keeles kommentaare kasutada ja millised on parimad tavad.

2. Kommentaaride tüübid C keeles

2.1. Mitmerealiste kommentaaride kasutamine

Mitmerealisi kommentaare kirjutatakse kujul /* … */. Selle abil saab lihtsalt lisada ühe või mitme rea pikkuseid märkusi. Näiteks on see kasulik kogu koodi või mitme protsessi kirjeldamiseks.

/* 
See programm võtab kasutajalt sisendi
ja teeb arvutused vastavalt sellele.
*/
int main() {
    // Käivitab protsessi
}

See vorm on eriti mugav, kui on vaja kommentaariblokki. Siiski ei saa /* ja */ kommenteerimist omavahel sisse pesastada, seega tuleb olla ettevaatlik.

2.2. Üherealiste kommentaaride kasutamine

C keel toetab ka üherealisi kommentaare. Selleks kirjuta // ja selle järel kommentaar – kõik pärast seda märki rea lõpuni loetakse kommentaariks. See on mugav lühikeste selgituste lisamiseks koodirea juurde.

int x = 10; // Omistab x-le väärtuse 10

Üherealised kommentaarid on kasulikud konkreetsete muutujate või toimingute selgitamiseks ning annavad koodile visuaalselt puhtama ilme. Seetõttu on soovitatav neid sageli kasutada.

3. Põhireeglid kommentaaride kirjutamisel

3.1. Kommentaaride mahu ja sisu optimeerimine

Kommentaarid on vahend vajaliku info edastamiseks, kuid liigne kommenteerimine võib olla hoopis kahjulik. Kui kommentaarid on liiga pikad või ilmselged, halvendab see koodi loetavust ja võib tekitada segadust. Kommentaare tuleks lisada ainult siis, kui need aitavad mõistmist.

Tarbetu kommentaari näide

int sum = a + b; // Liidab a ja b ning omistab sum-muutujale

See kommentaar on liig, sest selle sisu on koodist niigi arusaadav. Selliseid kommentaare tuleks vältida.

3.2. Kirjuta konkreetsed ja selged kommentaarid

See-eest keerukamate toimingute või raskemini mõistetavate osade puhul on oluline kirjutada selged ja konkreetsed kommentaarid. Kui selgitada koodi mõtet ja tausta, on seda hiljem palju lihtsam lugeda ka teistel arendajatel.

4. Kommentaaride kasutamise parimad tavad

4.1. Ühtne kommentaaristiil kogu projektis

Kogu projekti ulatuses ühtse kommentaaristiili hoidmine on eriti oluline meeskonnatöös. Kui erinevad arendajad töötavad sama koodiga, muudab ühtne stiil selle mõistmise palju lihtsamaks. Näiteks võiks ühtlustada kommentaaride asukoha, vormingu ja keele, et parandada koodi loetavust.

4.2. Dokumenteerivad kommentaarid

Kui on vaja funktsioonide või klasside kohta anda detailsemat infot, tuleks kasutada dokumenteerivaid kommentaare. Näiteks funktsiooni eesmärgi, argumentide ja tagastusväärtuste täpsem kirjeldus aitab uutel arendajatel kiiremini orienteeruda.

/**
 * @brief Funktsioon kahe täisarvu liitmiseks
 * @param a Esimene liidetav täisarv
 * @param b Teine liidetav täisarv
 * @return Kahe täisarvu summa
 */
int add(int a, int b) {
    return a + b;
}

5. Kommentaarid koodi hooldatavuse tõstmiseks

5.1. Kommentaarid aitavad hooldatavust parandada

Kommentaarid pole ainult selgitamiseks – need toetavad ka koodi hooldamist. Pikaajalistes projektides või suuremates koodibaasides on kommentaaridest palju abi, sest need võimaldavad mõista muudatuste tausta ja algset mõtet ka aastaid hiljem.

5.2. Kommentaaride uuendamine ja eemaldamine

Koodi muutmisel tuleb kindlasti ka kommentaare uuendada. Vanad kommentaarid, mis enam koodiga ei klapi, tekitavad segadust. Samuti tuleks tarbetud kommentaarid eemaldada, et hoida kood puhtana.

6. Kommentaaride praktilised kasutusviisid

6.1. Kommentaaride kasutamine silumisel ja testimisel

Koodi osade ajutiseks väljalülitamiseks – näiteks silumise või testimise ajal – sobib kommenteerimine väga hästi. Nii saab lihtsalt proovida koodi erinevaid osi ilma, et peaks neid kustutama.

int main() {
    int result = add(2, 3);
    // printf("Arvutuse tulemus: %d", result); // Silumiseks
}

6.2. Katsetuste ja muudatuste jälgimine

Kui katsetada erinevaid väärtusi või tingimusi, saab kommentaare kasutada alternatiivide säilitamiseks. See võimaldab arendajal proovida muudatusi, jättes algse koodi alles.

int main() {
    int result;
    result = add(1, /* 2 */ 3); // Muudeti algne 2 väärtuseks 3
    printf("%d", result);
}

7. Kokkuvõte

C keeles kommentaaride kasutamine on võimas tööriist koodi loetavuse ja hooldatavuse parandamiseks. Õigesti paigutatud ja regulaarselt hooldatud kommentaarid sujuvdavad arendajate vahelist suhtlust ja aitavad luua tõhusa arenduskeskkonna. Kommentaarid pole ainult lisainfo, vaid on oluline osa koodist.