1.2 — Komentarze

komentarz to czytelna dla programisty notatka wstawiana bezpośrednio do kodu źródłowego programu. Komentarze są ignorowane przez kompilator i są przeznaczone wyłącznie do użytku programisty.

W C++ istnieją dwa różne style komentarzy, z których oba służą temu samemu celowi: pomóc programistom w jakiś sposób udokumentować kod.

Komentarze jednowierszowe

Klasa // symbol rozpoczyna jednoliniowy komentarz w C++, który nakazuje kompilatorowi ignorowanie wszystkiego, od symbolu // do symbolu koniec linii. Na przykład:

std::cout << "Hello world!"; // Wszystko od tego miejsca do końca linii jest ignorowane

Zwykle komentarz jednoliniowy służy do szybkiego komentarza dotyczącego pojedynczej linii kodu.

std::cout << "Hello world!\n"; // std::cout znajduje się w bibliotece iostream
std::cout << "It is very nice to meet you!\n"; // te komentarze sprawiają, że kod trudny do odczytania
std::cout << "Yeah!\n"; // szczególnie gdy linie są różne długości

Umieszczenie komentarzy po prawej stronie linii może sprawić, że zarówno kod, jak i komentarz będą trudne do odczytania, szczególnie jeśli linia jest długa. Jeśli linie są dość krótkie, komentarze można po prostu wyrównać (zwykle do tabulatora), w następujący sposób:

std::cout << "Hello world!\n";                 // std::cout znajduje się w bibliotece iostream
std::cout << "It is very nice to meet you!\n"; // to jest znacznie łatwiejsze do odczytania
std::cout << "Yeah!\n";                        // nie sądzisz więc?

Jeśli jednak linie są długie, umieszczenie komentarzy po prawej stronie może spowodować, że linie będą naprawdę długie. W takim przypadku komentarze jednowierszowe są często umieszczane nad linią, którą komentuje:

// std::cout znajduje się w bibliotece iostream
std::cout << "Hello world!\n";

// to jest znacznie łatwiejsze do odczytania
std::cout << "It is very nice to meet you!\n";

// nie sądzisz więc?
std::cout << "Yeah!\n";

#include <iostream>

int main()
{
    // Zastąp tę linię fragmentem kodu, który chcesz skompilować

    return 0;
}

Komentarze wielowierszowe

Klasa /* i */ para symboli oznacza wieloliniowy komentarz w stylu C. Wszystko pomiędzy symbolami jest ignorowane.

/* To jest komentarz wielowierszowy.
   Ta linia pozostaniena.
   Ten też. */

Ponieważ wszystko pomiędzy symbolami jest ignorowane, czasami można zobaczyć, jak programiści „upiększają” swoje wieloliniowe komentarze:

/* To jest komentarz wielowierszowy.
 * pasujące gwiazdki po lewej stronie
 * może ułatwić czytanie
 */

Komentarze w stylu wielowierszowym nie mogą być zagnieżdżane. W rezultacie następujące skutki będą miały nieoczekiwane rezultaty:

/* To jest komentarz wieloliniowy /* */ this is not inside the comment */
// Powyższy komentarz kończy się na pierwszym */, a nie na drugim */

Kiedy kompilator spróbuje to skompilować, zignoruje wszystko od pierwszego /* do pierwszego */. Ponieważ this is not inside the comment */ nie uważanego za część komentarza, kompilator spróbuje go skompilować. To nieuchronnie spowoduje błąd kompilacji.

To jest jedno miejsce, w którym użycie podświetlania składni może być naprawdę przydatne, ponieważ różne kolorowanie komentarza powinno jasno wskazywać, co jest uważane za część komentarza, a co nie.

Właściwe użycie komentarzy

Zazwyczaj komentarzy należy używać do trzech celów. Po pierwsze, w przypadku danej biblioteki, programu lub funkcji komentarze najlepiej nadają się do opisania co działania biblioteki, programu lub funkcji. Są one zazwyczaj umieszczane na górze pliku lub biblioteki lub bezpośrednio przed funkcją. Na przykład:

// Ten program oblicza końcową ocenę ucznia na podstawie jego testu i wyniki pracy domowej.

// Ta funkcja wykorzystuje metodę Newtona do aproksymacji pierwiastka danego równania.

// Następujące wiersze generują losowy przedmiot na podstawie rzadkości, poziomu i współczynnika wagi.

Wszystkie te komentarze dają czytelnikowi dobre pojęcie o tym, co biblioteka, program lub funkcja próbuje osiągnąć, bez konieczności patrzenia na rzeczywisty kod. Użytkownik (być może ktoś inny lub Ty, jeśli próbujesz ponownie wykorzystać napisany wcześniej kod) na pierwszy rzut oka może stwierdzić, czy kod jest istotny dla tego, co próbuje osiągnąć. Jest to szczególnie ważne podczas pracy w zespole, gdzie nie każdy będzie zaznajomiony z całym kodem.

Po drugie, w bibliotece, programie lub funkcji opisanych powyżej komentarze mogą służyć do opisania jak kod osiągnie swój cel.

/* Aby obliczyć końcową ocenę, sumujemy wszystkie ważone prace semestralne i prace domowe wyniki
    a następnie podzieli przez liczbę punktów, aby przypisać procent, czyli
    używane do obliczania oceny literowej. */

// Aby wygenerować losowy element, wykonamy następujące czynności:
// 1) Umieść wszystkie elementy o żądanej rzadkości na lista
// 2) Oblicz a prawdopodobieństwo dla każdego elementu na podstawie poziomu i współczynnika wagi
// 3) Wybierz losową liczbę
// 4) Dowiedz się, któremu elementowi odpowiada ta liczba losowa
// 5) Zwróć odpowiednią pozycję

Te komentarze dają użytkownikowi wyobrażenie o tym, jak kod zamierza osiągnąć swój cel, bez konieczności rozumienia, co robi każda poszczególna linia kodu.

Po trzecie, na poziomie instrukcji komentarze powinny być użyte do opisania dlaczego kod coś robi. Zły komentarz do instrukcji wyjaśnia co działanie kodu. Jeśli kiedykolwiek napiszesz kod tak złożony, że wymaga komentarza, aby wyjaśnić co działanie instrukcji, prawdopodobnie będziesz musiał przepisać swoją instrukcję, a nie ją komentować.

Oto kilka przykładów złych komentarzy do linii i dobrych komentarzy do instrukcji.

Zły komentarz:

// Ustaw zasięg widzenia na 0
sight = 0;

Powód: Już widzimy, że widok jest ustawiony na 0, patrząc na instrukcję

Dobry komentarz:

// Gracz właśnie wypił miksturę ślepoty i nic nie widzi
sight = 0;

Powód: Teraz wiemy, dlaczego wzrok gracza jest ustawiony na 0

Zły komentarz:

// Oblicz koszt elementów
cost = quantity * 2 * storePrice;

Powód: Widzimy, że jest to kalkulacja kosztów, ale dlaczego ilość jest mnożona przez 2?

Dobry komentarz:

// Musimy tutaj pomnożyć ilość przez 2, ponieważ kupuje się je parami
cost = quantity * 2 * storePrice;

Powód: Teraz wiemy, dlaczego ta formuła sprawia, że sens.

Programiści często muszą podejmować trudną decyzję pomiędzy rozwiązaniem problemu w jeden lub inny sposób. Komentarze to świetny sposób, aby przypomnieć sobie (lub powiedzieć komuś innemu) powód, dla którego podjąłeś taką a nie inną decyzję.

Dobre komentarze:

// Zdecydowaliśmy się użyć połączonej listy zamiast tablicy, ponieważ
// tablice wstawiają się zbyt wolno.

// Będziemy używać metody Newtona do znalezienia pierwiastka liczby ponieważ
// nie ma deterministycznego sposobu rozwiązania tych równań.

Na koniec komentarze powinny być pisane w sposób zrozumiały dla kogoś, kto nie ma pojęcia, do czego służy kod. Często zdarza się, że programista powie: „To oczywiste, do czego to służy! Nie ma mowy, żebym o tym zapomniał”. Zgadnij co? To nie oczywiste, a Ty będziesz zdumiony, jak szybko zapominasz. :) Ty (lub ktoś inny) podziękujesz Ci później za spisanie w ludzkim języku tego, co, jak i dlaczego masz w kodzie. Czytanie poszczególnych linii kodu jest łatwe. Zrozumienie celu, jaki mają osiągnąć, nie jest możliwe.

Komentowanie kodu

Przekształcanie jednej lub więcej linii kodu w komentarz nazywa się komentowaniem swojego kodu. Zapewnia to wygodny sposób (tymczasowego) wykluczenia części kodu z skompilowanego programu.

Aby skomentować pojedynczą linię kodu, po prostu użyj komentarza w stylu //, aby tymczasowo zamienić linię kodu w komentarz:

Bez komentarza:

    std::cout << 1;

Komentowanie:

//    std::cout << 1;

Aby skomentować blok kodu, użyj // w wielu wierszach kodu lub komentarza w stylu /* */, aby tymczasowo zamienić blok kodu w komentarz.

Bez komentarza:

    std::cout << 1;
    std::cout << 2;
    std::cout << 3;

Komentowanie:

//    std::cout << 1;
//    std::cout << 2;
//    std::cout << 3;

lub

/*
    std::cout << 1;
    std::cout << 2;
    std::cout << 3;
*/

Jest kilka powodów, dla których możesz chcieć to zrobić:

1. Pracujesz nad nowym fragmentem kodu, który jeszcze się nie skompiluje, i musisz uruchomić program. Kompilator nie pozwoli ci skompilować kodu, jeśli wystąpią błędy kompilatora. Komentowanie kodu, który się nie skompiluje, umożliwi skompilowanie programu i umożliwienie jego uruchomienia. Kiedy będziesz gotowy, możesz odkomentować kod i kontynuować pracę nad nim.
2. Napisałeś nowy kod, który się kompiluje, ale nie działa poprawnie i nie masz czasu, aby go naprawić dopiero później. Komentowanie uszkodzonego kodu sprawi, że zepsuty kod nie zostanie wykonany i spowoduje problemy, dopóki go nie naprawisz.
3. Aby znaleźć źródło błędu. Jeśli program nie daje pożądanych rezultatów (lub ulega awarii), czasami przydatne może być wyłączenie części kodu, aby sprawdzić, czy uda się wyizolować przyczynę nieprawidłowego działania. Jeśli skomentujesz jedną lub więcej linii kodu, a Twój program zacznie działać zgodnie z oczekiwaniami (lub przestanie się zawieszać), istnieje duże prawdopodobieństwo, że to, co ostatnio skomentowałeś, było częścią problemu. Następnie możesz sprawdzić, dlaczego te linie kodu powodują problem.
4. Chcesz zastąpić jeden fragment kodu innym fragmentem kodu. Zamiast po prostu usuwać oryginalny kod, możesz go skomentować i pozostawić do wglądu, dopóki nie będziesz pewien, że nowy kod działa poprawnie. Gdy będziesz mieć pewność, że nowy kod działa, możesz usunąć stary, zakomentowany kod. Jeśli nie możesz uruchomić nowego kodu, zawsze możesz usunąć nowy kod i odkomentować stary, aby powrócić do tego, co miałeś wcześniej.

Komentowanie kodu jest częstą praktyką podczas programowania, dlatego wiele IDE zapewnia obsługę komentowania podświetlonej sekcji kodu. Sposób dostępu do tej funkcji różni się w zależności od środowiska IDE.

Streszczenie

• W bibliotece, programie lub funkcji poziomie użyj komentarzy do opisu co.
• Wewnątrz biblioteki, programu lub funkcji użyj komentarzy do opisu jak.
• Na poziomie instrukcji użyj komentarzy do opisania dlaczego.