Autor: Codenga 23.02.2024

O pisaniu dobrego kodu mówi się cały czas. Niezliczona ilość programistów ciągle dyskutuje nad wzorcami projektowymi, sposobami nazywania zmiennych itp. Niewiele czasu jednak poświęca się na pisanie dobrych komentarzy do kodu. A to przecież bardzo ważna część naszej pracy. W tym artykule omówimy kilka prostych i ważnych reguł pisania dobrych komentarzy.

Kod jest dla ludzi

Dobry kod to taki kod, który jest zrozumiały dla ludzi. A źle napisany komentarz, może być gorszy niż brak komentarza. Jak więc tworzyć dobre komentarze do kodu?

Komentarze nie powinny duplikować kodu

Początkujących programistów uczy się, żeby jak najczęściej komentowali kod. Często prowadzi do do nadmiaru komentarzy, które wyjaśniają każdy możliwy fragment kodu. Nawet jeśli ten kod bardzo prosty i zrozumiały dla każdego.

score = 10 // przypisanie do zmiennej a

Ten powyższy przykład dobrze ilustruje zjawisko nadmiarowego komentarza. Po co wyjaśniać komentarzem tak oczywistą rzecz, jak przypisanie do zmiennej? Taki komentarz nic nie wnosi, a praca poświęcona na jego utworzenie idzie na marne. Zastanów się dobrze, czy komentarze, które piszesz, rzeczywiście coś wnoszą do tematu.

Komentarze nie powinny zastępować dobrego kodu

Wróćmy do przykładu ze zmienną:

x = 1 // początkowy stan licznika

Zmienna x jest źle nazwana. Gdybyśmy ją od razu nazwali dobrze to komentarz nie byłby potrzebny. Skoro jest to początkowy stan licznika, to nazwijmy naszą zmienną odpowiednio:

initial_counter = 1

Teraz komentarz nie będzie potrzebny, bo nazwa zmiennej wyjaśnia od razu, do czego ona służy. Jeśli kod jest dobrze napisany, i nazwy zmiennych czy funkcji mają sens, to można spokojnie pominąć większość komentarzy.

Używaj prostego, zrozumiałego języka

Czasami zapominamy o rzeczach oczywistych. Komentarze powinny być zrozumiałe dla innych programistów. Powinny być proste i konkretne. Popatrz:

// Funkcja przetwarzająca dane wejściowe i zwracająca wynik na wyjściu
function processInput(inputData) {
    // Tutaj wykonujemy różne operacje na danych wejściowych,
    // używając różnych funkcji pomocniczych do manipulacji nimi.
    // Musimy upewnić się, że wynik końcowy jest poprawny i zgodny z oczekiwaniami.
    // Pamiętaj, żeby nie zapomnieć o szczegółach implementacyjnych
    // oraz o uwzględnieniu wszystkich krawędziowych przypadków.
    // Jest to krytyczne dla skutecznego działania funkcji.
    // Sprawdzamy, czy dane wejściowe są poprawne i czy nie występują żadne błędy.
    // Wszelkie wyjątki są obsługiwane w tej funkcji,
    // co zapewnia, że ​​funkcja nie zakończy się nieoczekiwanie.
    // Na koniec zwracamy przetworzone dane wyjściowe.
return processedData;
}
    

Powyższy komentarz to dużo treści, ale mało konkretów. Brakuje konkretnych informacji na temat tego, jakie operacje są wykonywane na danych wejściowych, jakie są oczekiwane wyniki i jakie są ewentualne przypadki brzegowe lub problemy, które mogą wystąpić. Czyli sporo tekstu, który niewiele wnosi do tematu.

Komentuj błędy znalezione w kodzie

Czasami komentarze dodajemy nie tylko podczas pisania kodu, ale także później, podczas jego modyfikacji. I to ma sens. Jeśli w kodzie znaleźliśmy błąd i udało nam się go usunąć, to czasem jest sens wyjaśnienia tego problemu za pomocą komentarza.

function isInternetExplorer() {
    // Poprawiono zachowanie dla Internet Explorer
    // Korzystamy z metody navigator.userAgent, która zwraca informacje o przeglądarce.
    // Jeśli w user agent znajduje się fraza "MSIE" lub "Trident", to znaczy, że używamy Internet Explorera.
return (navigator.userAgent.indexOf('MSIE') !== -1 || navigator.userAgent.indexOf('Trident') !== -1);
}

Komentarze w powyższym kodzie wyjaśniają, dlaczego ten kod został utworzony. Wyjaśniają, że jest on konieczny ze względu na odmienną implementację funkcji dla przeglądarki Internet Explorer.

Komentuj niedokończoną implementację

Bywa tak czasem, że musimy wrzucić do repozytorium kod, który nie został ukończony. W takiej sytuacji, warto wyraźnie zaznaczyć, że dana funkcja nie została w pełni zaimplementowana. Oto przykład

// TODO: Funkcja do filtrowania liczb parzystych w tablicy
function filterEvenNumbers(numbers) {
    // Ta funkcja ma zwrócić nową tablicę zawierającą tylko liczby parzyste
    // z przekazanej tablicy, jednak nie została jeszcze w pełni zaimplementowana.
    // Kod do uzupełnienia.
}
    

Mamy szkielet funkcji, która z jakiegoś powodu nie została jeszcze zaimplementowana. I wyraźnie to zaznaczamy, za pomocą komentarzy.

Komentuj nietypowe fragmenty kodu

Jeśli w kodzie masz jakąś nietypową implementację, to warto ją opisać za pomocą komentarzy. Popatrz na przykład:

// Ta funkcja stosuje alternatywne metody odczytu plików dla przeglądarek Internet Explorer,
// które nie obsługują interfejsu FileReader. Używa metody ActiveX dla obsługi plików.
function readFile(file) {
    if (isInternetExplorer()) {
        // Kod obsługi plików dla Internet Explorera za pomocą ActiveX.
    } else {
        // Standardowa obsługa plików za pomocą interfejsu FileReader.
    }
} 

W kodzie mamy nietypową implementację dla starej przeglądarki. Tutaj użycie komentarzy ma sens - za ich pomocą uzasadniamy i wyjaśniamy nasz nietypowy kod.

Podsumowanie

W artykule opisaliśmy reguły pisania dobrych komentarzy. Pokazaliśmy, że komentarz nie powinny powielać kodu. Powinny być pisane prostym, zrozumiałym językiem. Powinny być konkretne. Dobrze napisane komentarze są wartościowym sposobem na dokumentowanie kodu i bardzo ułatwiają pracę w zespole.