Komentarze w C++: jednoliniowe // i wieloliniowe /* */

Do czego służą komentarze

Komentarz to tekst w kodzie źródłowym, który kompilator C++ całkowicie ignoruje. Nigdy nie trafia do skompilowanego programu: istnieje wyłącznie dla ludzi czytających kod. Komentarzy używasz, aby wyjaśnić, dlaczego coś zrobiono w określony sposób, zostawić przypomnienia albo tymczasowo wyłączyć kod bez usuwania go.

Opierając się na znanej ci już składni C++: komentarze to jedna z niewielu rzeczy, które możesz wstawić niemal wszędzie, a kompilator po prostu je pominie. C++ ma dwa rodzaje: jednoliniowe (//) i wieloliniowe komentarze blokowe (/* */).

Komentarze jednoliniowe

Dwa ukośniki (//) rozpoczynają komentarz, który trwa do końca bieżącej linii. Kompilator pomija wszystko od // do końca linii.

#include <iostream>
using namespace std;

int main() {
    // Wypisz powitanie w konsoli
    cout << "Hello, C++!" << endl;

    int score = 90; // komentarz może też stać po kodzie
    cout << score << endl;
    return 0;
}

Zwróć uwagę, że drugi komentarz dzieli linię z prawdziwym kodem. Wszystko przed // nadal się wykonuje; ignorowana jest tylko część po nim. To najczęstszy styl komentarzy dla krótkich notatek.

Wieloliniowe komentarze blokowe

Gdy notatka zajmuje kilka linii, komentarz blokowy jest czytelniejszy niż poprzedzanie każdej linii przez //. Komentarz blokowy zaczyna się od /* i kończy na */. Wszystko pomiędzy, niezależnie od liczby linii, jest ignorowane.

#include <iostream>
using namespace std;

int main() {
    /*
     * Ten program pokazuje komentarz blokowy.
     * Gwiazdki na początku każdej linii to tylko
     * konwencja poprawiająca czytelność: nie są wymagane.
     */
    cout << "Block comments are handy." << endl;
    return 0;
}

Wyrównane znaki * na początku kolejnych linii to konwencja stylu, a nie reguła. Naprawdę liczą się tylko otwierające /* i zamykające */. Komentarz blokowy może nawet stać w środku linii (int x = 5 /* width */ + 2; jest poprawne), choć szybko robi się to nieczytelne.

Zakomentowywanie kodu

Komentarze to standardowy sposób na wyłączenie kodu podczas eksperymentów bez jego usuwania. Użyj // dla jednej linii albo komentarza blokowego, aby wyłączyć kilka linii naraz.

#include <iostream>
using namespace std;

int main() {
    cout << "This line runs." << endl;

    // cout << "This line is disabled." << endl;

    /*
    cout << "So is this one," << endl;
    cout << "and this one too." << endl;
    */

    cout << "This line runs as well." << endl;
    return 0;
}

Uruchom to, a zobaczysz tylko dwie linie z "runs". Zakomentowane instrukcje cout są dla kompilatora niewidoczne.

Pułapka braku zagnieżdżania

Pułapka, w którą wpadają początkujący: komentarze blokowe się nie zagnieżdżają. Pierwsze */ zamyka komentarz, niezależnie od tego, ile /* pojawiło się wcześniej. Nie możesz więc owinąć bloku /* ... */ w inny blok /* ... */: wewnętrzne */ kończy całość, a wszystko po nim znowu staje się kodem (zwykle z błędem składni).

/*  Trying to disable a region that already has a block comment...
    int n = 10; /* the width */
    cout << n;
*/  // the first */ above already closed the comment - this line is now stray code

Zewnętrzny komentarz kończy się na */ po the width, więc reszta nie jest już zakomentowana, a kompilator dławi się końcowym */. Gdy musisz wyłączyć obszar, który już zawiera komentarze blokowe, postaw // w każdej linii. Większość edytorów przełącza komentarze liniowe dla całego zaznaczenia jednym skrótem klawiszowym, co całkowicie omija problem.

Dobre komentarze a szum

Komentarz powinien wyjaśniać coś, czego kod nie powie sam. Komentarze, które tylko powtarzają kod, dodają bałaganu i z czasem przestają zgadzać się z kodem, gdy ten się zmienia.

// Bad: just repeats what the code obviously does
i = i + 1; // add one to i

// Better: explains the reason, which the code can't show
retries++; // back off and retry; the API is rate-limited at 5 req/sec

Staraj się, aby to kod był czytelny dzięki jasnym nazwom i strukturze, a komentarze zostaw na dlaczego: intencję, kompromisy, przypadki brzegowe i odnośniki do kontekstu. Jeśli piszesz komentarz, żeby wyjaśnić zagmatwaną linię, to często znak, że lepiej zmienić nazwę zmiennej albo wydzielić logikę do dobrze nazwanej funkcji.

Dalej: zmienne

Umiesz już opisywać swój kod, więc kolejny element to przechowywanie w nim danych. Następna strona omawia zmienne: jak je deklarować, jakie wbudowane typy przechowują i jakie reguły wymusza C++, bo jest językiem statycznie typowanym.