Komentarze w C: // i /* */ wyjaśnione

Komentarz to tekst, który kompilator wyrzuca. Istnieje wyłącznie dla ludzi, którzy będą później czytać kod, a jednym z nich zwykle jesteś ty. C oferuje dwie formy, a zrozumienie, kiedy która jest właściwym narzędziem, zajmuje jakieś dwie minuty.

Dwie formy

#include <stdio.h>

int main(void) {
    // Komentarz jednoliniowy: wszystko od // do końca linii.

    /* Komentarz blokowy.
       Może obejmować dowolnie wiele linii
       i kończy się dopiero na znaczniku zamykającym. */

    printf("Komentarze nigdy nie trafiaja na wyjscie.\n");  // mogą też stać za kodem
    return 0;
}

Uruchom to: wynik ma jedną linię. Oba komentarze zostały usunięte, zanim kompilator w ogóle przeanalizował program; nic nie kosztują w czasie działania i nic nie dodają do pliku wykonywalnego.

// trwa do końca fizycznej linii. Nic nie może stać za nim w tej linii, więc to nie działa tak, jak wygląda:

int x = 5;  // ustaw x na pięć  int y = 6;   /* y nigdy nie zostaje zadeklarowane */

/* ... */ kończy się na pierwszym */, gdziekolwiek ono jest. Może zaczynać się i kończyć w środku linii, co czasem się przydaje:

int total = price /* przed podatkiem */ + shipping;

Dlaczego istnieją dwa style

/* */ to oryginalne C z 1972 roku. // przyszło z C++ i zostało oficjalnie dodane do C dopiero w C99. Ta historia wyjaśnia coś, co zauważysz, czytając starszy kod: biblioteki pisane z myślą o przenośności do C89 używają /* */ nawet dla komentarzy jednoliniowych, bo // nie skompilowałoby się na starych narzędziach, które wciąż wspierały.

Dziś każdy kompilator, którego raczej użyjesz, akceptuje oba. Używaj // do zwykłych uwag, a /* */, gdy komentarz naprawdę zajmuje kilka linii. Jeśli celujesz w bardzo stary kompilator dla systemów wbudowanych, sprawdź to, zanim zaczniesz polegać na //.

Komentarzy nie da się zagnieżdżać

To jedyna prawdziwa pułapka:

/* Na razie wyłącz tę sekcję
   int a = compute();
   /* klasyczna funkcja pomocnicza: miej ją na oku */
   int b = a * 2;
*/

Komentarz blokowy kończy się na pierwszym */, czyli tym w linii 3. Linie 4 i 5 są wtedy znowu żywym kodem, a końcowe */ w linii 6 to błąd składni. Komunikat kompilatora wskazuje ostatnią linię i nic nie mówi o przyczynie.

Rozwiązaniem jest użycie preprocesora, który radzi sobie z zagnieżdżaniem:

#if 0
    int a = compute();
    /* klasyczna funkcja pomocnicza: miej ją na oku */
    int b = a * 2;
#endif

#if 0 nigdy nie jest prawdą, więc preprocesor usuwa wszystko aż do #endif, zanim kompilator to zobaczy. Radzi sobie z komentarzami, cudzysłowami i innymi blokami #if w środku, a przy sprzątaniu łatwo go wyszukać.

Zakomentowywanie kodu podczas debugowania

Tymczasowe usunięcie linii to najczęstsze codzienne zastosowanie komentarzy. Gdy program zachowuje się dziwnie, wyłączanie po jednej instrukcji pokazuje, która z nich ma znaczenie.

#include <stdio.h>

int main(void) {
    int total = 0;

    for (int i = 1; i <= 5; i++) {
        total += i;
        // printf("krok %d: total = %d\n", i, total);  /* włącz, żeby śledzić */
    }

    printf("Suma koncowa: %d\n", total);
    return 0;
}

Odkomentuj printf i uruchom ponownie, żeby zobaczyć, jak pętla buduje wynik. Śledzenie wypisywaniem nie jest eleganckie, ale w C jest szybkie i zawsze działa: debugger powie ci więcej, a printf powie ci coś od razu.

Dwa nawyki chronią przed bałaganem. Usuwaj zakomentowany kod, zanim zrobisz commit; system kontroli wersji pamięta starą wersję, więc ty nie musisz. A gdy celowo zostawiasz wyłączoną linię, napisz obok, dlaczego.

Komentarze dokumentacyjne

Komentarz blokowy nad funkcją to miejsce, w którym wyjaśniasz, co ona robi, co znaczą jej parametry i co w niej zaskakującego.

#include <stdio.h>

/*
 * celsius_to_fahrenheit
 * ---------------------
 * Zamienia temperaturę w stopniach Celsjusza na stopnie Fahrenheita.
 *
 *   c: temperatura wejściowa w stopniach Celsjusza
 *
 * Zwraca równoważną temperaturę w stopniach Fahrenheita.
 */
double celsius_to_fahrenheit(double c) {
    return c * 9.0 / 5.0 + 32.0;
}

int main(void) {
    printf("100C = %.1fF\n", celsius_to_fahrenheit(100.0));
    printf("0C   = %.1fF\n", celsius_to_fahrenheit(0.0));
    return 0;
}

Narzędzia takie jak Doxygen czytają takie ustrukturyzowane komentarze i generują z nich dokumentację referencyjną. Własny styl Doxygena używa /** ... */ ze znacznikami @param i @return:

/**
 * Zamienia stopnie Celsjusza na stopnie Fahrenheita.
 * @param c temperatura w stopniach Celsjusza
 * @return ta sama temperatura w stopniach Fahrenheita
 */
double celsius_to_fahrenheit(double c);

Do własnego kodu nada się każdy z nich. Liczy się to, żeby komentarz był obok deklaracji, którą ludzie czytają, zwykle w pliku nagłówkowym, a nie zakopany w implementacji.

Co warto komentować

Zasada, która przetrwa zetknięcie z prawdziwym kodem: komentuj dlaczego, a nie co.

i++;  // zwiększ i          <- nie mówi nic, czego nie powiedział kod

/* Pomiń BOM: pliki eksportowane przez stary system zaczynają się
   od trzech bajtów, które nie są częścią danych. */
offset += 3;

Drugi komentarz zawiera informację, której nie ma nigdzie w kodzie. Pierwszy to szum, który w końcu zacznie przeczyć linii, którą opisuje, bo komentarzy nikt nie aktualizuje, gdy kod się zmienia.

Rzeczy, które w C szczególnie warto skomentować:

• Kto jest właścicielem tej pamięci. Jeśli funkcja zwraca wskaźnik, który wywołujący musi zwolnić przez free, napisz to. C nie ma jak wyrazić tego w typie.
• Jednostki i zakresy. int timeout; jest niejednoznaczne: sekundy czy milisekundy?
• Nieoczywista poprawność. Dlaczego pętla kończy się na n - 1, dlaczego to rzutowanie jest bezpieczne, dlaczego bufor ma 256 bajtów.
• Celowe dziwactwa. Kod, który wygląda na błąd, ale nim nie jest, przyciąga "poprawki" przyszłych czytelników, chyba że jest opisany.

#include <stdio.h>
#include <string.h>

int main(void) {
    char name[32];  /* 31 znaków plus kończący '\0' */

    /* strncpy NIE dodaje terminatora, jeśli źródło wypełni bufor,
       więc zapisujemy go sami. */
    strncpy(name, "Ada Lovelace", sizeof(name) - 1);
    name[sizeof(name) - 1] = '\0';

    printf("Imie: %s\n", name);
    return 0;
}

Ten komentarz zasługuje na swoje miejsce: linia pod nim wygląda na zbędną, a nie jest.

Komentarze w stringach to nie komentarze

Ostatni szczegół. Znaczniki komentarzy nie mają specjalnego znaczenia wewnątrz literału stringowego ani stałej znakowej:

#include <stdio.h>

int main(void) {
    printf("Postep: 50%% // to nie komentarz\n");
    printf("Sciezka to /* nadal zwykly tekst */\n");
    return 0;
}

Obie linie wypisują się w całości. Kompilator dzieli stringi na tokeny, zanim zacznie szukać komentarzy, więc // w cudzysłowie to po prostu dwa znaki. (%% w pierwszej linii to sposób na wypisanie dosłownego znaku procentu przez printf: samo % rozpoczyna specyfikator formatu.)