Komentarze i formatowanie kodu

W Parku Jurajskim dobra dokumentacja i staranne zarządzanie informacjami są kluczowe dla bezpieczeństwa – zarówno pracowników, jak i gości. Jeden nieprecyzyjny opis zachowania dinozaura albo nieczytelne notatki dotyczące procedury bezpieczeństwa mogą prowadzić do katastrofalnych konsekwencji.

Podobnie w świecie JavaScript, komentarze i odpowiednie formatowanie kodu są fundamentalnymi praktykami, które zapewniają, że twój kod będzie zrozumiały, łatwy w utrzymaniu i bezpieczny.

Komentarze w JavaScript

Komentarze to fragmenty tekstu w kodzie, które są ignorowane przez interpreter JavaScript. Służą wyłącznie programistom do dokumentowania kodu, wyjaśniania jego działania lub tymczasowego wyłączania fragmentów kodu podczas testów.

Komentarze jednoliniowe

Komentarz jednoliniowy rozpoczyna się od dwóch ukośników (

//

). Wszystko, co znajduje się po prawej stronie tych znaków w danej linii, jest traktowane jako komentarz.

1// To jest komentarz jednoliniowy
2let velociraptorCount = 3; // Liczba Velociraptorów w zagrodzie B

Komentarze wieloliniowe

Komentarze wieloliniowe (blokowe) rozpoczynają się od znaku

/*

i kończą znakiem

*/

. Wszystko, co znajduje się między tymi znacznikami, jest traktowane jako komentarz, nawet jeśli obejmuje wiele linii.

1/* 
2   To jest komentarz wieloliniowy.
3   Może obejmować kilka linii.
4   Protokół bezpieczeństwa dla zagrody T-Rexów:
5   1. Sprawdź zasilanie ogrodzenia
6   2. Upewnij się, że wszystkie bramy są zamknięte
7   3. Monitoruj aktywność co 15 minut
8*/
9
10let safetyChecklist = ["zasilanie", "bramy", "monitoring"];

Praktyczne zastosowania komentarzy

Komentarze w JavaScript służą różnym celom, podobnie jak różne rodzaje dokumentacji w Parku Jurajskim:

1. Dokumentacja kodu

1/**
2 * Oblicza bezpieczną odległość od zagrody dinozaura.
3 * @param {string} dinoType - Gatunek dinozaura
4 * @param {number} dinoCount - Liczba dinozaurów w zagrodzie
5 * @param {boolean} isElectricFenceActive - Czy ogrodzenie elektryczne jest aktywne
6 * @returns {number} Bezpieczna odległość w metrach
7 */
8function calculateSafeDistance(dinoType, dinoCount, isElectricFenceActive) {
9    // Implementacja funkcji...
10    return distance;
11}

Ta forma komentarzy (JSDoc) jest szczególnie przydatna, ponieważ wiele edytorów kodu (jak VS Code) używa jej do wyświetlania dokumentacji podczas pisania kodu.

2. Wyjaśnienie skomplikowanej logiki

1// Algorytm przewidywania wzorca ucieczki Velociraptorów
2// Opiera się na analizie 10 poprzednich prób ucieczek
3// i wykorzystuje wzorzec zachowania opisany przez dr. Granta
4if ((attemptTime > sunsetTime && attemptTime < sunriseTime) && 
5    (weatherCondition === 'storm' || fencePowerLevel < 80)) {
6    // Podwyższone ryzyko ucieczki - aktywuj dodatkowe zabezpieczenia
7    activateSecondaryContainment();
8}

3. Tymczasowe wyłączanie kodu (komentowanie)

1// Stara metoda karmienia - obecnie nieużywana
2// function feedDinosaurs(dinoType) {
3//     if (dinoType === 'herbivore') {
4//         providePlants();
5//     } else {
6//         provideMeat();
7//     }
8// }
9
10// Nowa metoda karmienia z uwzględnieniem diety
11function feedDinosaurs(dinoType, specialDiet) {
12    // Implementacja uwzględniająca specjalne diety
13}

4. Znaczniki TODO/FIXME/NOTE

1// // FIXME: Naprawić błąd w liczeniu dinozaurów podczas deszczu
2// NOTE: API parku może się zmienić w przyszłym miesiącu

Takie znaczniki są często wyróżniane przez edytory kodu i mogą być łatwo znalezione, gdy pracujesz nad kodem.

Dobre praktyki dotyczące komentarzy

Tak jak w Parku Jurajskim nieaktualne lub mylące informacje mogą być niebezpieczne, tak w kodzie złe praktyki komentowania mogą prowadzić do problemów:

Co robić:

1. Pisz komentarze, które wyjaśniają "dlaczego", a nie "co"

   1// ŹLE:
   2// Zwiększa liczbę dinozaurów o 1
   3dinoCount++;
   4
   5// DOBRZE:
   6// Uwzględniamy nowo wykluty okaz z laboratorium
   7dinoCount++;

2. Utrzymuj komentarze aktualne Gdy zmieniasz kod, aktualizuj również komentarze. Nieaktualne komentarze są gorsze niż brak komentarzy.

3. Używaj jasnego i precyzyjnego języka Tak jak w protokołach bezpieczeństwa, jednoznaczność jest kluczowa.

Czego unikać:

1. Nadmiarowego komentowania

   1// ŹLE:
   2// Deklaracja zmiennej z liczbą dinozaurów
   3let dinoCount = 15;
   4
   5// DOBRZE: (bez komentarza, bo kod jest samoopisujący)
   6let dinoCount = 15;

2. Komentarzy, które zaciemniają kod

   1/* Uwaga! Ten kod jest skomplikowany i tylko senior może go zrozumieć.
   2   Zmieniaj na własne ryzyko! */

3. Nieaktualnych komentarzy

   1// ŹLE:
   2// Sprawdza, czy jest 7 dinozaurów
   3if (dinoCount > 10) { // Kod się zmienił, ale komentarz pozostał nieaktualny

Formatowanie kodu

Podobnie jak precyzyjne mapy i plany Parku Jurajskiego są niezbędne do efektywnego zarządzania, tak odpowiednie formatowanie kodu JavaScript jest kluczowe dla czytelności i utrzymania.

Wcięcia i odstępy

Konsekwentne stosowanie wcięć (zazwyczaj 2 lub 4 spacje) pomaga wizualnie rozróżnić bloki kodu:

1function checkParkSecurity() {
2    if (fencesActive) {
3        // Poziom 1 wcięcia
4        for (let sector of parkSectors) {
5            // Poziom 2 wcięcia
6            if (sector.hasCarnivores) {
7                // Poziom 3 wcięcia
8                runExtraChecks(sector);
9            }
10        }
11    } else {
12        // Poziom 1 wcięcia
13        activateEmergencyProtocol();
14    }
15}

Nawiasy klamrowe

Istnieją dwa główne style umieszczania nawiasów klamrowych:

Styl K&R (Kernighan & Ritchie)

1function checkFences() {
2    if (powerLevel < 50) {
3        sendAlert();
4        activateBackupGenerator();
5    } else {
6        logStatus("Ogrodzenia działają prawidłowo");
7    }
8}

Styl Allman

1function checkFences()
2{
3    if (powerLevel < 50)
4    {
5        sendAlert();
6        activateBackupGenerator();
7    }
8    else
9    {
10        logStatus("Ogrodzenia działają prawidłowo");
11    }
12}

W JavaScript bardziej powszechny jest styl K&R.

Konwencje nazywania

Jak w przypadku precyzyjnego nazewnictwa dinozaurów, tak i w JavaScript należy stosować jasne konwencje nazewnictwa:

1// camelCase dla zmiennych i funkcji
2let velociraptorCount = 3;
3function checkSecuritySystems() { }
4
5// PascalCase dla klas i konstruktorów
6class DinosaurPaddock { }
7
8// UPPER_CASE dla stałych
9const MAX_VISITORS_PER_TOUR = 8;
10const PARK_OPENING_HOURS = {
11    start: 8,
12    end: 20
13};

Spacje wokół operatorów

Dla poprawy czytelności, warto stosować spacje wokół operatorów:

1// Trudne do odczytania
2let safetyRating=parkSectors.length>0?parkSectors.filter(s=>s.securityLevel<3).length/parkSectors.length*100:0;
3
4// Łatwiejsze do odczytania
5let safetyRating = parkSectors.length > 0 
6    ? parkSectors.filter(s => s.securityLevel < 3).length / parkSectors.length * 100 
7    : 0;

Długość linii

Utrzymywanie rozsądnej długości linii (zwykle 80-120 znaków) pomaga w czytaniu kodu bez konieczności przewijania w poziomie:

1// Zbyt długa linia
2const fullSecurityCheck = checkElectricFences() && checkMotionSensors() && checkCameraSystem() && checkRadioSystem() && staffMembersPresent >= minimumStaffRequired && weatherCondition !== 'storm';
3
4// Podzielone na łatwiejsze do przeczytania części
5const fullSecurityCheck = 
6    checkElectricFences() && 
7    checkMotionSensors() && 
8    checkCameraSystem() && 
9    checkRadioSystem() && 
10    staffMembersPresent >= minimumStaffRequired && 
11    weatherCondition !== 'storm';

Grupowanie powiązanego kodu

Organizowanie kodu w logiczne grupy poprawia jego czytelność:

1// Inicjalizacja zmiennych
2const parkName = "Jurassic Park";
3const openingYear = 1993;
4const isOpen = true;
5
6// Sprawdzanie stanu zagrody
7const fenceStatus = checkFences();
8const dinoHealth = monitorDinoVitals();
9const securityBreach = checkForBreaches();
10
11// Raportowanie
12generateStatusReport(fenceStatus, dinoHealth);
13if (securityBreach) {
14    alertSecurityTeam();
15}

Narzędzia do formatowania kodu

W nowoczesnym rozwoju JavaScript istnieje wiele narzędzi automatyzujących formatowanie kodu, podobnie jak zaawansowane systemy monitoringu w Parku Jurajskim automatyzują wiele zadań ochrony:

• Prettier - automatycznie formatuje kod według ustalonych reguł
• ESLint - sprawdza kod pod kątem błędów i niestandardowych praktyk
• EditorConfig - pomaga utrzymać spójne formatowanie między różnymi edytorami i programistami

Standardy i style kodowania

Tak jak Park Jurajski ma swoje procedury i protokoły, w świecie JavaScript istnieją różne uznane standardy stylu kodu:

• Airbnb JavaScript Style Guide - jeden z najpopularniejszych zbiorów zasad
• Google JavaScript Style Guide - używany w projektach Google
• StandardJS - minimalistyczny styl bez konfiguracji

Praktyczne ćwiczenie

Przyjrzyj się poniższemu nieformatowanemu kodowi i zastanów się, jak mógłbyś go poprawić, stosując poznane zasady:

1// nieformatowany kod
2function trackDino(dinoId,name,   species,location){
3// sprawdza pozycję dinozaura
4let status='unknown';
5if(location){status='tracked'}else{
6    // nie znaleziono dinozaura
7    status='lost';
8    triggerAlert(dinoId)
9}
10// zapisuj dane do systemu
11return{id:dinoId,name:name,species,
12    status:status,lastSeen:location?new Date():null}}
13// wywołanie funkcji
14const result=trackDino(42,'Blue','Velociraptor',{x:234,y:189});

A teraz porównaj go z prawidłowo sformatowaną wersją:

1/**
2 * Śledzi położenie dinozaura i aktualizuje jego status w systemie
3 * @param {number} dinoId - Identyfikator dinozaura
4 * @param {string} name - Imię dinozaura
5 * @param {string} species - Gatunek dinozaura
6 * @param {Object|null} location - Współrzędne położenia lub null jeśli nie znaleziono
7 * @returns {Object} Aktualizowane dane dinozaura
8 */
9function trackDino(dinoId, name, species, location) {
10    // Sprawdza pozycję dinozaura
11    let status = 'unknown';
12    
13    if (location) {
14        status = 'tracked';
15    } else {
16        // Nie znaleziono dinozaura - aktywacja procedury alarmowej
17        status = 'lost';
18        triggerAlert(dinoId);
19    }
20    
21    // Zapisuje dane do systemu monitoringu
22    return {
23        id: dinoId,
24        name: name,
25        species,
26        status: status,
27        lastSeen: location ? new Date() : null
28    };
29}
30
31// Śledzenie dinozaura "Blue"
32const result = trackDino(42, 'Blue', 'Velociraptor', { x: 234, y: 189 });

Podsumowanie

Komentarze i formatowanie kodu w JavaScript, podobnie jak dokumentacja i procedury w Parku Jurajskim, są niezbędne do utrzymania porządku, bezpieczeństwa i efektywności. Dobrze skomentowany i sformatowany kod:

1. Jest łatwiejszy do zrozumienia przez ciebie i innych programistów
2. Zmniejsza ryzyko błędów i "ucieczek" (bugów)
3. Ułatwia utrzymanie i rozwój projektu w przyszłości
4. Poprawia współpracę w zespole

Pamiętaj, że tak jak w Parku Jurajskim, gdzie zaniedbanie może prowadzić do katastrofy (pamiętasz, co się stało, gdy Dennis Nedry wyłączył systemy bezpieczeństwa?), tak w kodzie zaniedbane praktyki mogą prowadzić do trudno wykrywalnych błędów i problemów z utrzymaniem.

W następnych lekcjach będziemy konsekwentnie stosować te dobre praktyki, budując coraz bardziej zaawansowane elementy naszego wirtualnego Parku Jurajskiego z użyciem JavaScript.