Komentarze w kodzie źródłowym

pliki z tekstem

W tym artykule zostanie poruszony temat pisania komentarzy w kodzie źródłowym. Często powstają dyskusje na temat tego, czy pisać komentarze, czy też z nich zrezygnować. A może istnieje kompromis? 🙂

Możemy wyróżnić trzy główne podejścia do pisania komentarzy w kodzie źródłowym:

  1. Pisanie dużej ilości komentarzy.
  2. Zrezygnowanie z pisania komentarzy.
  3. Pisanie komentarzy, ale tylko tam, gdzie jest to konieczne.

Podejście numer 3 stanowi dobry kompromis pomiędzy dwoma pierwszymi podejściami. W artykule przedstawię fragmenty kodu źródłowego z rzeczywistego projektu – gry komputerowej, którą zaimplementowałem w 2014 roku. Gra została zaimplementowana w języku Java. Zamieszczone fragmenty kodu źródłowego prezentują się podobnie w innych językach programowania.

komentarze w kodzie źródłowym - zrzut ekranu z analizowanego kodu źródłowego gry 2048 Hex
Zrzut ekranu z zaimplementowanej gry. Jest to implementacja gry 2048, ale w wersji dla programistów 🙂. Liczby wyświetlane są w systemie szesnastkowym 🙂

Poniżej znajduje się definicja metody o nazwie addGamerPoints:

// adding points for gamer
private void addGamerPoints(int x, int y) {
    pointsCounter.add(numericBoxes[x][y].getGameNumber());
}

Powyżej definicji metody znajduje się komentarz. W tym przypadku komentarz jest zbędny. Komentarz powtarza informację zawartą w nazwie metody. Komentarz z powodzeniem może zostać usunięty. Poniżej znajduje się kolejny fragment kodu, który odpowiada za wykonanie jednego z kroków algorytmu gry:

// 2. step: merge boxes
for (int y = 0; y < boardHeight; y++) {
    for (int x = 0; x < boardWidth - 1; x++) {
        // ...
    }
}

Powyżej pętli for znajduje się komentarz: 2. step: merge boxes. Gdyby komentarz został usunięty bez żadnych innych zmian w kodzie to utracilibyśmy informację o przeznaczeniu tego fragmentu kodu. W tym przypadku możemy zastąpić komentarz poprzez utworzenie pomocniczej metody. W wyniku tej operacji otrzymujemy następujący kod:

private void mergeBoxes() {
    for (int y = 0; y < boardHeight; y++) {
        for (int x = 0; x < boardWidth - 1; x++) {
            // ...
        }
    }
}

Poniżej znajduje się definicja klasy o nazwie Position. Przy definicji klasy znajduje się komentarz. Komentarz opisuje zakres widoczności klasy. W języku Java gdy nie określimy jawnie zakresu widoczności klasy, wtedy domyślnym zakresem jest dostęp wewnątrz pakietu. W innych językach programowania również możemy spotkać się z zakresami widoczności klas, metod, funkcji. W tym przypadku komentarz jest nadmiarowy, ponieważ opisuje składnię języka programowania. Z powodzeniem możemy usunąć komentarz Just package scope.

/*
 * Just package scope.
 */
class Position {

    int x, y;

}

Poniżej znajduje się ostatni fragment kodu, który zostanie poddany analizie:

Scene scene = new Scene(root, NumericConstants.DEFAULT_WINDOW_WIDTH.getProperty(), NumericConstants.DEFAULT_WINDOW_HEIGHT.getProperty());
// scene.getStylesheets().add(stylesheet);

W ostatniej linii znajduje się zakomentowany kod. Jest to przykład złej praktyki. Zakomentowana linia kodu powinna zostać wyjaśniona. Jeżeli kod jest wykorzystywany to powinien zostać odkomentowany. Jeżeli kod nie jest już wykorzystywany to powinien zostać usunięty.

Podsumowanie:

  • częste opisywanie w komentarzach co wykonuje dany kod jest zbędne,
  • komentarze mają swój koszt utrzymania – jeśli kod się zmieni to również jest wymagane zaktualizowanie komentarzy,
  • zamiast opisywania w komentarzach co dany kod wykonuje, można skorzystać z opisowych nazw funkcji, metod, parametrów,
  • nie jest możliwe całkowite pozbycie się z komentarzy – czasami należy skorzystać z komentarzy do wyjaśnienia dlaczego w kodzie wybrano dane rozwiązanie,
  • należy starać się nie pozostawiać zakomentowanego kodu.

Dziękuję za przeczytanie artykułu 🙂.

1 myśl na “Komentarze w kodzie źródłowym”

  1. Pingback: Magiczne liczby w kodzie źródłowym - Konstrukcja oprogramowania

Dodaj komentarz

Twój adres email nie zostanie opublikowany. Pola, których wypełnienie jest wymagane, są oznaczone symbolem *