Komentarze

W javascript istnieją 2 rodzaje komentarzy: komentarze zajmujące jedną i wiele linii:


/*
Przykład komentarza składającego się z wielu linii.
Taki komentarz może zawierać wiele linii.
*/
console.log('To jest mój pierwszy skrypt');

//To jest przykład komentarza 1-liniowego
console.log('To jest mój pierwszy skrypt')

Co za dużo to niezdrowo

Pierwsza sprawa - nie bój się komentować swojego kodu.

Z drugiej strony staraj się nie przesadzać. Komentarze powinny być dodatkowym opisem rzeczy mało oczywistych, ogólnym opisem danych kawałków kodu, ale równocześnie nie powinniśmy nimi opisywać każdej czynności jaką wykonujemy:


//przykłady złych komentarzy:

//robię pętlę od 1 do 100
for (let i=0; i<100; i++) {
    console.log("Lubie koty i psy"); //wypisuję w konsoli
}

Jedna z zasad mówi, że dobry kod powinien być na tyle czytelny, że może obejść się bez zbytecznych komentarzy.

Dla nas programistów oznacza to tyle, że nie musimy komentować każdej linii kodu, ale równocześnie naszym zadaniem nie jest pisanie jak najkrótszego kodu, a przede wszystkim możliwie czytelnego (co w dzisiejszych czasach - szczególnie w postach na grupach - wcale normą nie jest).

Komentowanie

Pisząc bardziej rozbudowane aplikacje warto przyłożyć się do opisywania funkcjonalności. Możemy to oczywiście robić tak jak nam jest wygodnie, ale warto tutaj spróbować używać składni JSDoc:


/**
 * Tworzy listę elementów
 * @param id
 * @param number
 * @param parent
 */
function createElementsList(id, number, parent) {

}

Komentarze takie możemy tworzyć ręcznie, ale możemy też użyć odpowiedniego narzędzia.

W Webstorm aby wstawić taki komentarz, wystarczy przed funkcją wpisać /** i nacisnąć Enter. Dodatkowy opis znajdziesz tutaj.

W przypadku Visual Studio Code działamy podobnie czyli znowu wpisujemy /** i naciskamy enter. Aby jednak podpowiadało nam odpowiednią składnię, musimy zaopatrzyć się w dodatek.

Gdy ładnie opiszemy nasz kod za pomocą takich komentarzy, możemy później skorzystać z narzędzia jsdoc, które automatycznie wygeneruje nam dokumentację do naszego kodu.

Więcej na ten temat możesz przeczytać na stronie https://jsdoc.app/.

Komentarze TODO

Za pomocą komentarzy rozpoczynających się od TODO czy FIXME możemy oznaczać miejsca, w których będziemy chcieli w przyszłości coś zmienić albo dorobić.


//TODO: Tutaj muszę zaimplementować funkcjonalność...

if (...) {
    //FIXME: poprawić funkcjonalność
}

Podobne komentarze możemy stosować w każdym języku - w HTML, CSS, Javascript czy innych.


<body>
    <!-- TODO: tutaj muszę chyba dodać fajny bajer na stronie -->

    <style>
        /* TODO: zmienić to stylowanie */
        body {
            background: black;
            color: #333;
        }
    </style>
</body>

Najpopularniejsze edytory posiadają funkcjonalność, która pozwala wyświetlić listę takich komentarzy w danym projekcie, dzięki czemu bardzo szybko możemy między nimi się przemieszczać.

W Webstorm funkcjonalność taka widnieje w okienku TODO, które możemy odpalić skrótem Alt + 6. Możemy też je otworzyć odpalając okno wyszukiwania akcji (Ctrl + Shift + A, lub Shift, Shift), wpisując TODO, po czym nacisnąć Enter.

W przypadku Visual Studio Code musimy zainstalować sobie dodatek dla TODO - np. Todo Tree.

Skrót klawiaturowy

Korzystając ze swojego edytora wyrabiaj sobie nawyki.

Jednym z takich nawyków jest używanie komentarzy. Aby wstawić nowy komentarz, stawiasz kursor w danej linii (w dowolnym jej miejscu), po czym naciskasz klawisze Ctrl + /. Aby odkomentować daną linię, robimy to samo.

Podobnie możemy komentować i odkomentowywać kawałki kodu. Wystarczy zaznaczyć dany kawałek po czym nacisnąć powyższą Ctrl + /. Jeżeli zamiast tej kombinacji naciśniemy Ctrl + Shift + / wstawimy komentarz wieloliniowy (taki o - /* */), przy czym nie jest to wymagane, ponieważ za pomocą // możemy spokojnie komentować całe kawałki kodu.

Metoda ta zadziała w każdym języku. Pamiętaj więc - jeżeli chcesz gdziekolwiek wstawić komentarz - czy to w CSS, HTML, Javascript czy podobnych - Ctrl + / są twoim przyjacielem.

Pierwszy skrypt Okna dialogowe