Komentarze w kodzie: Rodzaje i dobre praktyki
Dowiedz się, jak poprawnie używać komentarzy w programowaniu. Poznaj rodzaje komentarzy jednoliniowych, wieloliniowych i dokumentacyjnych.
Komentarze i ich rodzaje
Kod źródłowy piszemy dla maszyn, ale czytają go ludzie. Komentarze to fragmenty programu, które są całkowicie ignorowane przez kompilator lub interpreter. Ich jedynym celem jest pomoc programiście w zrozumieniu, dlaczego dany fragment kodu powstał i jak działa.
Komentarz
Rodzaje komentarzy
Większość języków programowania oferuje dwa podstawowe sposoby komentowania, a niektóre dodają do tego specjalne bloki dokumentacyjne.
| Cecha | Typ | Zastosowanie |
|---|---|---|
| Jednoliniowy | Krótki opis w jednej linii | // To jest komentarz |
| Wieloliniowy | Dłuższe wyjaśnienia, bloki kodu | /* Treść komentarza */ |
| Dokumentacyjny | Generowanie dokumentacji API | /** @param id */ |
Kiedy używać komentarzy?
Dobry komentarz nie opisuje tego, co robi kod (to powinno wynikać z nazw zmiennych), ale dlaczego został napisany w taki, a nie inny sposób.
Wyjaśnienie intencji
Komentowanie skomplikowanych algorytmów lub nietypowych rozwiązań, które nie są oczywiste na pierwszy rzut oka.
Komentowanie oczywistości
Opisywanie prostych operacji, np. i = i + 1; // zwiększ o jeden. To tylko zaśmieca kod.
Kod jako dokumentacja
Dąż do tego, by Twój kod był tak czysty, by komentarze były potrzebne tylko w wyjątkowych sytuacjach.
Najczęstsze błędy i pułapki
Dezaktualizacja komentarzy
Zostawianie 'martwego' kodu
Przykłady w różnych językach
Zobacz, jak składnia komentarzy różni się w zależności od wybranej technologii:
// Komentarz jednoliniowy
/*
Komentarz
wieloliniowy
*/Pro Tipy
Używaj TODO
Checklista dobrego komentowania
Zanim napiszesz komentarz, sprawdź:
0/4Quiz: Sprawdź wiedzę
Co dzieje się z komentarzami podczas procesu kompilacji programu?
Schemat przepływu (Mermaid)
Co dalej?
- Dowiedz się, czym jest Javadoc i jak automatycznie generować dokumentację z kodu.
- Przeczytaj o standardach Clean Code dotyczących komentowania.
- Sprawdź, jak działają Docstringi w języku Python.
- Naucz się skrótu klawiszowego do szybkiego komentowania (zazwyczaj Ctrl + /).
- Rozwiąż zadania z INF.04, zwracając uwagę na czytelność zapisywanego kodu.
Może Cię zainteresować
Operatory Relacyjne i Logiczne: Jak porównywać dane?
Zrozum, jak działają operatory porównania oraz jak łączyć warunki za pomocą AND, OR i NOT. Kluczowa wiedza do instrukcji sterujących.
Operator Warunkowy: Skrócony if-else w jednej linii
Poznaj operator trójargumentowy (ternary). Dowiedz się, jak skracać kod i kiedy warto go używać zamiast klasycznej instrukcji if-else.
Operatory matematyczne: Fundament obliczeń w kodzie
Poznaj podstawowe i zaawansowane operatory matematyczne. Dowiedz się, jak działa modulo, inkrementacja oraz dlaczego kolejność działań ma znaczenie.