Aby prawidłowo udokumentować linię kodu języka JavaScript, należy po znakach // wpisać komentarz
x = Math.max(a,b,c); //
A. wybór losowej wartości ze zmiennych a, b i c.
B. nieprawidłowe dane.
C. w zmiennej x maksymalna wartość ze zmiennych a, b, c.
D. w zmiennej x minimalna wartość ze zmiennych a, b, c.
Komentarz po znakach // powinien krótko i rzeczowo wyjaśniać, co robi dana linia kodu. W tym przypadku instrukcja x = Math.max(a, b, c); wywołuje metodę Math.max, czyli wbudowaną funkcję JavaScript zwracającą największą wartość spośród przekazanych argumentów. Jeżeli na przykład a = 4, b = 12, a c = 7, to do zmiennej x zostanie przypisana liczba 12. Dlatego komentarz w stylu: w zmiennej x maksymalna wartość ze zmiennych a, b, c jest poprawny i dobrze opisuje sens operacji. Moim zdaniem to jest też fajny przykład dobrego komentarza: nie tłumaczy każdego znaku składni, tylko mówi, jaki jest efekt działania kodu. W praktyce komentarze warto pisać tam, gdzie kod może nie być od razu jasny, np. przy obliczeniach, warunkach biznesowych albo nietypowych założeniach. Zgodnie z dobrymi praktykami branżowymi komentarz powinien być aktualny, krótki i pomagać w utrzymaniu aplikacji, a nie powtarzać bezmyślnie kodu. W JavaScript // oznacza komentarz jednoliniowy, więc wszystko po tych znakach do końca linii nie jest wykonywane przez interpreter.
W tym fragmencie łatwo pomylić znaczenie metody Math.max z innymi operacjami, szczególnie gdy patrzy się tylko na nazwy zmiennych a, b i c. Kod x = Math.max(a, b, c); nie sprawdza poprawności danych i sam z siebie nie oznacza komunikatu o nieprawidłowych danych. Oczywiście, jeżeli do funkcji trafią wartości nienumeryczne, wynik może być NaN, ale to już efekt konkretnych danych wejściowych, a nie podstawowy cel tej instrukcji. Komentarz powinien opisywać normalne działanie kodu, a nie przypadkową sytuację wyjątkową bez widocznej obsługi błędu. Nie chodzi tu także o losowanie wartości. W JavaScript losowanie wykonuje się zwykle przez Math.random, często połączone z Math.floor albo innymi obliczeniami. Math.max nie wybiera elementu przypadkowo, tylko porównuje argumenty i deterministycznie zwraca największy z nich. To ważna różnica, bo dla tych samych wartości wejściowych wynik Math.max zawsze będzie taki sam. Błędne jest też skojarzenie tej instrukcji z wartością minimalną. Do wyszukania najmniejszej liczby służy Math.min(a, b, c), czyli metoda o podobnej składni, ale przeciwnym znaczeniu. Z mojego doświadczenia uczniowie często patrzą tylko na ogólny kształt zapisu Math.coś i zgadują działanie po kontekście, zamiast przeczytać nazwę funkcji. Dobra praktyka w dokumentowaniu kodu polega na tym, żeby komentarz był zgodny z faktyczną semantyką instrukcji. Tutaj zmienna x dostaje maksymalną, czyli największą wartość spośród a, b i c. Taki opis pomaga później przy debugowaniu i utrzymaniu skryptu, bo od razu wiadomo, jaki wynik powinien powstać po wykonaniu tej linii.