Nie komentuj swojego kodu (za dużo): jak pisać samoopisujący się kod

Komentowanie kodu to jedno z pierwszych zagadnień, które poznajemy jako programiści. Wielu początkujących developerów uczy się, że „dobry kod powinien być dobrze komentowany”. Jednak z czasem, w miarę zdobywania doświadczenia, okazuje się, że zbyt wiele komentarzy może bardziej zaszkodzić niż pomóc. Kod powinien być czytelny i samoopisujący się — tak, aby każda osoba, która go przegląda, mogła zrozumieć jego logikę bez potrzeby czytania obszernej dokumentacji w postaci komentarzy.

Nadmierne komentowanie prowadzi do takich problemów, jak:

• Zwiększona trudność w utrzymaniu kodu: gdy kod ewoluuje, komentarze często stają się nieaktualne.
• Przeładowanie informacjami: zbyt wiele tekstu wokół kodu może sprawić, że trudno znaleźć kluczowe fragmenty logiki.
• Odruchowe zaufanie do komentarzy: zamiast analizować kod, programiści ufają komentarzom, które mogą być błędne.

Co oznacza „kod samoopisujący się”

Kod samoopisujący się to taki, który dzięki czytelnej strukturze, odpowiednim nazwom zmiennych, funkcji czy klas oraz zrozumiałym konstrukcjom logicznym wyjaśnia swoje działanie bez potrzeby dodawania komentarzy. Kluczowe cechy takiego kodu to:

• Dobre nazewnictwo: Zamiast pisać komentarz // obliczanie średniej, użyj funkcji o nazwie calculateAverage().
• Podział na mniejsze funkcje: Każda funkcja powinna mieć jeden cel. Zamiast wielkiej funkcji obsługującej wiele zadań, rozbij kod na mniejsze moduły, które jasno określają swoją rolę.
• Unikanie złożoności: Staraj się uprościć logikę, eliminując zbędne konstrukcje i upraszczając warunki.

Przykład:

zamiast tego:

// Funkcja zwraca największą liczbę z podanej tablicy
function findMaxValue(array $numbers): int {
    $max = $numbers[0]; // Przypisanie pierwszego elementu jako początkowego maksimum

    // Iteracja po wszystkich liczbach
    foreach ($numbers as $number) {
        if ($number > $max) { // Sprawdzenie, czy aktualna liczba jest większa niż obecne maksimum
            $max = $number; // Aktualizacja maksymalnej wartości
        }
    }

    return $max; // Zwracanie maksymalnej liczby
}

napisz:

function findMaxValue(array $numbers): int {
    $max = $numbers[0];

    foreach ($numbers as $number) {
        if ($number > $max) {
            $max = $number;
        }
    }

    return $max;
}

Druga wersja eliminuje potrzebę komentarza, ponieważ logika jest oczywista dzięki przejrzystej konstrukcji.

Komentarze: kiedy są konieczne?

Komentarze nadal mają swoje miejsce w kodzie, ale powinny być używane z rozwagą. Główna zasada brzmi: wyjaśnij „dlaczego”, a nie „co”.

Kiedy warto dodać komentarz:

1. Wyjaśnienie złożonej logiki biznesowej: Jeśli fragment kodu odzwierciedla skomplikowaną regułę biznesową, która nie jest oczywista, warto dodać komentarz. przykład: # Wyliczanie rabatu dla klientów VIP w oparciu o regułę z działu finansowego discount = price * 0.15 if customer.is_vip else price * 0.05
2. Wskazanie ograniczeń technicznych: Gdy kod jest napisany w określony sposób z powodu ograniczeń środowiska lub bibliotek. przykład: // Używamy jQuery, bo biblioteka A nie wspiera dynamicznych selektorów $('.element').addClass('active');
3. Dodanie informacji historycznych: Wyjaśnienie, dlaczego coś zostało zmienione, jest często przydatne, szczególnie w dużych projektach. przykład: // Zmieniono w wersji 3.2, aby obsługiwać nowych dostawców API

Kiedy unikać komentarzy:

• Wyjaśnianie oczywistości: nie dodawaj komentarzy tam, gdzie kod sam to tłumaczy.
• Aktualizowanie statusu projektu: komentarze typu // TODO mogą być przydatne, ale nie powinny zastępować systemu zarządzania zadaniami.
• Powielanie kodu w komentarzu: jeśli komentarz opisuje dokładnie to, co robi linia kodu, jest zbędny.

Utrzymanie komentarzy w aktualnym stanie

Nieaktualne komentarze są gorsze niż brak komentarzy. Mogą wprowadzać w błąd innych programistów, prowadząc do błędnych założeń. Dlatego:

• Każdorazowo przy zmianie kodu, przeglądaj komentarze i aktualizuj je, jeśli są niezgodne z nową logiką.
• Staraj się unikać długich komentarzy, które trudniej utrzymać w aktualnym stanie.

Analiza wpływu na biznes

Stosowanie się do zasady „mniej komentarzy, więcej samoopisującego się kodu” przynosi korzyści nie tylko dla zespołu developerskiego, ale także dla całej organizacji. Oto kilka powodów:

• Skrócenie czasu wprowadzania nowych programistów: czytelny kod zmniejsza czas potrzebny na wdrożenie nowej osoby do projektu.
• Zwiększenie jakości kodu: mniejsze ryzyko błędów wynikających z nieaktualnych komentarzy.
• Redukcja kosztów utrzymania: przejrzysty kod wymaga mniej pracy podczas refaktoryzacji.

Strategia wdrożenia

Wprowadzenie tej zasady do zespołu wymaga edukacji i konsekwencji:

1. Szkolenia dla zespołu: organizuj warsztaty z czytelnego pisania kodu.
2. Kodyfikacja zasad w standardach zespołowych: dodaj regułę dotyczącą stosowania komentarzy w wewnętrznych wytycznych.
3. Przeglądy kodu: podczas code review, zwracaj uwagę na nadmiar komentarzy i sugeruj refaktoryzację.

Komentarze powinny być używane oszczędnie, aby kod pozostał czytelny i łatwy w utrzymaniu. Skupiaj się na pisaniu kodu, który sam tłumaczy swoje działanie, a komentarze rezerwuj do wyjaśniania intencji, złożonej logiki biznesowej lub ograniczeń technicznych.