Komentowanie kodu

Autor: Dondu

Kurs języka C: Spis treści

Każdy kod powinien zawierać komentarze. Im dokładniej opiszesz poszczególne fragmenty kodu, tym łatwiej będzie Ci go pisać (gdy jest duży) lub modyfikować po upływie dłuższego czasu.

Dodatkowo gdy masz problem i pokazujesz komuś swój kod np. na forum, osoba go sprawdzająca będzie mogła szybko zrozumieć jego działanie, co zachęca do pomagania i skraca czas znalezienia błędu.

W języku C możesz wykorzystać dwa rodzaje komentarza:

• /* ... tutaj komentarz ... */
• //   ... tutaj komentarz ... 

/* ... tutaj komentarz ... */

To podstawowy rodzaj komentarza. Umożliwia pisanie komentarzy zawierających znaki specjalne jak np. znak nowej linii, czyli umożliwia pisanie komentarza w wielu linijkach. Komentarz rozpoczyna się w miejscu wstawienia znacznika startu komentarza /* i kończy w miejscu umieszczenia znacznika końca */

Innymi słowy cały tekst komentarza musi się zawierać pomiędzy znacznikami początku i końca komentarza.

Przykład 1 (w kompilatorze)

/* Przykład komentarza jednoliniowego */

/* To jest przykład komentarza,
który zawiera się
w wielu linijkach */

/*
   Można także pisać
   bardziej 
   przejrzyście.
*/

Komentarz zawarty pomiędzy znacznikami /* oraz */ jest ignorowany przez kompilator, przez co możesz umieszczać go np. wewnątrz linijek kodu. Jednakże osobiście odradzam takie wykorzystanie komentarzy.

Przykład 2 (w kompilatorze)

a = 2 * /* komentarz */ 3;

//   ... tutaj komentarz ... 

Ten rodzaj komentarza umożliwia umieszczanie komentarza od miejsca umieszczenia znacznika  //  do końca linii. W związku z tym, każda nowa linia komentarza musi zaczynać się od znacznika //


Przykład 3 (w kompilatorze)

//pierwsza linia komentarza
//druga
//trzecia
//itd.

Ten rodzaj komentarza możesz wykorzystać także na końcu linii kodu. Umożliwia to bardzo przejrzyste komentowanie poszczególnych jego fragmentów.

Przykład 4 (w kompilatorze)

 //deklaracja zmiennych
 int a;  //zawiera dane o ilości królików w lesie 
 
 //sprawdzamy ilość królików
 if(a>2){
    a=a-12;  //pomniejsz ilość o dwanaście
 }else{
    a=a+3;   //powiększ ilość o 3
 }

Komentowanie mieszane

Oba rodzaje komentowania można wykorzystywać w sposób pokazany w poniższym przykładzie. Pozwala to na wykorzystanie komentarza /* ... */ do "zamarkowania" bloku nieużywanego kodu, w którym są wykorzystane komentarze //

Jest to w szczególności przydatne w czasie szukania przyczyn nie działania kodu. Możesz w ten sposób szybko sprawdzać różne jego wersje.

Przykład 5 (w kompilatorze)

//deklaracja zmiennych
int a;  //zawiera dane o ilości królików w lesie 
 

/*  wyłączyłem ten fragment kodu na czas szukania błędu
    //sprawdzamy ilość królików
    if(a>2){
       a=a-12;  //pomniejsz ilość o dwanaście
    }else{
       a=a+3;   //powiększ ilość o 3
    }
*/

    
a = a+1;  //wstawiłem tylko na czas szukania błędu

Kolor komentarzy

Gdy w kodzie jest sporo komentarzy, może to utrudnić wzrokowe przeglądanie kodu. Ja radzę sobie z tym poprzez odpowiednie dobranie koloru komentarzy w edytorze kodu. Na przykład w MPLAB Microchipa ustawiłem sobie kolor #A4E3B7, by znacząco zwiększyć czytelność kodu.

Kurs języka C: Spis treści

32