1.2 — Komentarze

A 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!"; // Everything from here to the end of the line is ignored

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

std::cout << "Hello world!\n"; // std::cout lives in the iostream library
std::cout << "It is very nice to meet you!\n"; // these comments make the code hard to read
std::cout << "Yeah!\n"; // especially when lines are different lengths

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 lives in the iostream library
std::cout << "It is very nice to meet you!\n"; // this is much easier to read
std::cout << "Yeah!\n";                        // don't you think so?

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 lives in the iostream library
std::cout << "Hello world!\n";

// this is much easier to read
std::cout << "It is very nice to meet you!\n";

// don't you think so?
std::cout << "Yeah!\n";

#include <iostream>

int main()
{
    // Replace this line with the snippet(s) of code you'd like to compile

    return 0;
}

Komentarze wielowierszowe

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

/* This is a multi-line comment.
   This line will be ignored.
   So will this one. */

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

/* This is a multi-line comment.
 * the matching asterisks to the left
 * can make this easier to read
 */

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

/* This is a multi-line /* comment */ this is not inside the comment */
// The above comment ends at the first */, not the second */

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:

// This program calculates the student's final grade based on their test and homework scores.

// This function uses Newton's method to approximate the root of a given equation.

// The following lines generate a random item based on rarity, level, and a weight factor.

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.

/* To calculate the final grade, we sum all the weighted midterm and homework scores
    and then divide by the number of scores to assign a percentage, which is
    used to calculate a letter grade. */

// To generate a random item, we're going to do the following:
// 1) Put all of the items of the desired rarity on a list
// 2) Calculate a probability for each item based on level and weight factor
// 3) Choose a random number
// 4) Figure out which item that random number corresponds to
// 5) Return the appropriate item

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:

// Set sight range to 0
sight = 0;

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

Dobry komentarz:

// The player just drank a potion of blindness and can not see anything
sight = 0;

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

Zły komentarz:

// Calculate the cost of the items
cost = quantity * 2 * storePrice;

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

Dobry komentarz:

// We need to multiply quantity by 2 here because they are bought in pairs
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:

// We decided to use a linked list instead of an array because
// arrays do insertion too slowly.

// We're going to use Newton's method to find the root of a number because
// there is no deterministic way to solve these equations.

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.