Kurs JavaScript i TypeScript · Moduł 1: Podstawy JavaScript
Komentarze i formatowanie kodu
W tej lekcji7
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.
// To jest komentarz jednoliniowy
let velociraptorCount = 3; // Liczba Velociraptorów w zagrodzie BKomentarze 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.
/*
To jest komentarz wieloliniowy.
Może obejmować kilka linii.
Protokół bezpieczeństwa dla zagrody T-Rexów:
1. Sprawdź zasilanie ogrodzenia
2. Upewnij się, że wszystkie bramy są zamknięte
3. Monitoruj aktywność co 15 minut
*/
let 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
/**
* Oblicza bezpieczną odległość od zagrody dinozaura.
* @param {string} dinoType - Gatunek dinozaura
* @param {number} dinoCount - Liczba dinozaurów w zagrodzie
* @param {boolean} isElectricFenceActive - Czy ogrodzenie elektryczne jest aktywne
* @returns {number} Bezpieczna odległość w metrach
*/
function calculateSafeDistance(dinoType, dinoCount, isElectricFenceActive) {
// Implementacja funkcji...
return distance;
}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
// Algorytm przewidywania wzorca ucieczki Velociraptorów
// Opiera się na analizie 10 poprzednich prób ucieczek
// i wykorzystuje wzorzec zachowania opisany przez dr. Granta
if ((attemptTime > sunsetTime && attemptTime < sunriseTime) &&
(weatherCondition === 'storm' || fencePowerLevel < 80)) {
// Podwyższone ryzyko ucieczki - aktywuj dodatkowe zabezpieczenia
activateSecondaryContainment();
}3. Tymczasowe wyłączanie kodu (komentowanie)
// Stara metoda karmienia - obecnie nieużywana
// function feedDinosaurs(dinoType) {
// if (dinoType === 'herbivore') {
// providePlants();
// } else {
// provideMeat();
// }
// }
// Nowa metoda karmienia z uwzględnieniem diety
function feedDinosaurs(dinoType, specialDiet) {
// Implementacja uwzględniająca specjalne diety
}4. Znaczniki TODO/FIXME/NOTE
// TODO: Dodać obsługę nowego gatunku w harmonogramie karmienia
// FIXME: Naprawić błąd w liczeniu dinozaurów podczas deszczu
// NOTE: API parku może się zmienić w przyszłym miesiącuTakie 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ć:
Pisz komentarze, które wyjaśniają "dlaczego", a nie "co"
// ŹLE: // Zwiększa liczbę dinozaurów o 1 dinoCount++; // DOBRZE: // Uwzględniamy nowo wykluty okaz z laboratorium dinoCount++;Utrzymuj komentarze aktualne Gdy zmieniasz kod, aktualizuj również komentarze. Nieaktualne komentarze są gorsze niż brak komentarzy.
Używaj jasnego i precyzyjnego języka Tak jak w protokołach bezpieczeństwa, jednoznaczność jest kluczowa.
Czego unikać:
Nadmiarowego komentowania
// ŹLE: // Deklaracja zmiennej z liczbą dinozaurów let dinoCount = 15; // DOBRZE: (bez komentarza, bo kod jest samoopisujący) let dinoCount = 15;Komentarzy, które zaciemniają kod
/* Uwaga! Ten kod jest skomplikowany i tylko senior może go zrozumieć. Zmieniaj na własne ryzyko! */Nieaktualnych komentarzy
// ŹLE: // Sprawdza, czy jest 7 dinozaurów if (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:
function checkParkSecurity() {
if (fencesActive) {
// Poziom 1 wcięcia
for (let sector of parkSectors) {
// Poziom 2 wcięcia
if (sector.hasCarnivores) {
// Poziom 3 wcięcia
runExtraChecks(sector);
}
}
} else {
// Poziom 1 wcięcia
activateEmergencyProtocol();
}
}Nawiasy klamrowe
Istnieją dwa główne style umieszczania nawiasów klamrowych:
Styl K&R (Kernighan & Ritchie)
function checkFences() {
if (powerLevel < 50) {
sendAlert();
activateBackupGenerator();
} else {
logStatus("Ogrodzenia działają prawidłowo");
}
}Styl Allman
function checkFences()
{
if (powerLevel < 50)
{
sendAlert();
activateBackupGenerator();
}
else
{
logStatus("Ogrodzenia działają prawidłowo");
}
}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:
// camelCase dla zmiennych i funkcji
let velociraptorCount = 3;
function checkSecuritySystems() { }
// PascalCase dla klas i konstruktorów
class DinosaurPaddock { }
// UPPER_CASE dla stałych
const MAX_VISITORS_PER_TOUR = 8;
const PARK_OPENING_HOURS = {
start: 8,
end: 20
};Spacje wokół operatorów
Dla poprawy czytelności, warto stosować spacje wokół operatorów:
// Trudne do odczytania
let safetyRating=parkSectors.length>0?parkSectors.filter(s=>s.securityLevel<3).length/parkSectors.length*100:0;
// Łatwiejsze do odczytania
let safetyRating = parkSectors.length > 0
? parkSectors.filter(s => s.securityLevel < 3).length / parkSectors.length * 100
: 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:
// Zbyt długa linia
const fullSecurityCheck = checkElectricFences() && checkMotionSensors() && checkCameraSystem() && checkRadioSystem() && staffMembersPresent >= minimumStaffRequired && weatherCondition !== 'storm';
// Podzielone na łatwiejsze do przeczytania części
const fullSecurityCheck =
checkElectricFences() &&
checkMotionSensors() &&
checkCameraSystem() &&
checkRadioSystem() &&
staffMembersPresent >= minimumStaffRequired &&
weatherCondition !== 'storm';Grupowanie powiązanego kodu
Organizowanie kodu w logiczne grupy poprawia jego czytelność:
// Inicjalizacja zmiennych
const parkName = "Jurassic Park";
const openingYear = 1993;
const isOpen = true;
// Sprawdzanie stanu zagrody
const fenceStatus = checkFences();
const dinoHealth = monitorDinoVitals();
const securityBreach = checkForBreaches();
// Raportowanie
generateStatusReport(fenceStatus, dinoHealth);
if (securityBreach) {
alertSecurityTeam();
}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:
// nieformatowany kod
function trackDino(dinoId,name, species,location){
// sprawdza pozycję dinozaura
let status='unknown';
if(location){status='tracked'}else{
// nie znaleziono dinozaura
status='lost';
triggerAlert(dinoId)
}
// zapisuj dane do systemu
return{id:dinoId,name:name,species,
status:status,lastSeen:location?new Date():null}}
// wywołanie funkcji
const result=trackDino(42,'Blue','Velociraptor',{x:234,y:189});A teraz porównaj go z prawidłowo sformatowaną wersją:
/**
* Śledzi położenie dinozaura i aktualizuje jego status w systemie
* @param {number} dinoId - Identyfikator dinozaura
* @param {string} name - Imię dinozaura
* @param {string} species - Gatunek dinozaura
* @param {Object|null} location - Współrzędne położenia lub null jeśli nie znaleziono
* @returns {Object} Zaktualizowane dane dinozaura
*/
function trackDino(dinoId, name, species, location) {
// Sprawdza pozycję dinozaura
let status = 'unknown';
if (location) {
status = 'tracked';
} else {
// Nie znaleziono dinozaura - aktywacja procedury alarmowej
status = 'lost';
triggerAlert(dinoId);
}
// Zapisuje dane do systemu monitoringu
return {
id: dinoId,
name: name,
species,
status: status,
lastSeen: location ? new Date() : null
};
}
// Śledzenie dinozaura "Blue"
const 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:
- Jest łatwiejszy do zrozumienia przez ciebie i innych programistów
- Zmniejsza ryzyko błędów i "ucieczek" (bugów)
- Ułatwia utrzymanie i rozwój projektu w przyszłości
- 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.
Kod do tej lekcji: index.js
// Rejestr Dinozaurów - Tworzenie Obiektów
// Ćwiczenie: Tworzenie i modyfikacja obiektów JavaScript
// Obiekt to kolekcja właściwości (klucz: wartość)
const trex = {
name: "Tyrannosaurus Rex",
period: "Kreda późna",
diet: "mięsożerny",
weight: 7000,
isDangerous: true
};
console.log("=== Profil T-Rex ===");
console.log("Nazwa:", trex.name);
console.log("Dieta:", trex["diet"]);
console.log("Waga:", trex.weight, "kg");
// Dodawanie nowej właściwości
trex.enclosure = "Sektor A";
console.log("Zagroda:", trex.enclosure);
// Twoje zadanie:
// 1. Stwórz obiekt raptor z właściwościami: name, speed, packSize, isAlpha
// 2. Wyświetl jego właściwości
// 3. Dodaj nową właściwość
// Twój kod tutaj:
Hasła z dokumentacji w tej lekcji
Widzisz błąd w tej lekcji?
Sprawdź się
Odpowiedz na pytania z tej lekcji. Wybierz odpowiedź, a od razu zobaczysz, czy jest poprawna.
1. Jak rozpoczyna się komentarz jednoliniowy w JavaScript?
2. Która konwencja nazewnictwa jest standardem dla zmiennych i funkcji w JavaScript?
Zadania praktyczne w grze
- Klikanie w kolejności
Ułóż elementy komentarza wieloliniowego w JavaScript: