Koncepcje programowania/Komentarze

Czym są komentarze? To specjalnie sformatowany fragment kodu źródłowego, za pomocą którego opisujemy poszczególne części programu, bo zazwyczaj kody źródłowe naszych programów będą rozbudowane i pozwalają nam zrozumieć, która część kodu za co odpowiada. Bo np. Za rok możemy nie pamiętać w jaki sposób napisali program, inni programiści czytający nasz kod także może mieć problem z początkowym zrozumieniem go.

Czyli w komentarzach wpisujemy treść, zrozumiałą dla człowieka, opisujemy do czego służą poszczególne fragmenty kodu źródłowego i te komentarza są po prostu ignorowane przez komputer.

Komentarze w Pythonie mamy liniowe, czyli obejmujący jedną linię, jeden wiersz. Skutkuje to zignorowaniem całej pojedynczej linijki kodu. Stawiając znak "hasha" (#), zaraz po nim możemy pisać co chcemy i jak chcemy.

# To jest treść komentarza

Przykład w języku JavaScript:

// To jest treść komentarza

Przykład w języku elisp:

; To jest treść komentarza

Można też wstawiać komentarze śród liniowy, czyli taki komentarz, który pojawia się w tej samej linii co wykonywalny kod programu:

print("Hello World") # To jest treść komentarza

lub

alert("Hello World") // To jest treść komentarza

Trzecim rodzajem komentarzy jest komentarz blokowy, nazywany także jako wielowierszowy czy też wielolinijkowy. Pozwala on na pisanie dowolnych znaków w obrębie WIELU linijek i to jest cała różnica pomiędzy jednym, a drugim. Formułuje się nieco trudniej. W jednej linijce wstawiamy /*, a następnie tam gdzie ma się on kończyć, stawiamy */

Przykład w języku JavaSript:

/*
to
jest
komentarz
blokowy
*/

W języku Python, nie ma formalnego sposobu na wstawianie komentarzy blokowych. Pewną niepisaną zasadą programistów w jego przypadku, jest używanie do tego celu łańcuchów, znanych z poprzedniego rozdziału, czyli trzech apostrofów:

'''
to
jest
komentarz
blokowy
'''

Aczkolwiek jeśli chcemy to robić jak najbardziej poprawnie, warto zaopatrzyć się w edytor tekstu kodu źródłowego, który ułatwi nam pracę i będzie wstawiał samodzielnie znak # w momencie gdy będziemy tworzyć komentarze blokowe.

Zadania

1. Napisz program bez komentarzy i poproś kogoś innego, aby spróbował go zrozumieć. Następnie dodaj komentarze do kodu i poproś ich o ponowne wypróbowanie. Porównaj dwa doświadczenia i omów znaczenie komentarzy w kodzie.
2. Napisz program z nadmiernie szczegółowymi komentarzami, które wyjaśniają każdy wiersz kodu. Poproś kogoś innego o przeczytanie kodu i sprawdzi, czy uważają, że komentarze są pomocne lub przytłaczające. Omów równowagę między pomocnymi i niepotrzebnymi komentarzami w kodzie.
3. Napisz program i celowo pomiń kilka ważnych komentarzy. Poproś kogoś innego o przeczytanie kodu i sprawdzi, czy może zidentyfikować brakujące komentarze. Omów znaczenie włączenia wszystkich niezbędnych komentarzy do kodu.
4. Napisz program z komentarzami, które są niejasne lub mylące. Poproś kogoś o przeczytanie kodu i sprawdzi, czy mogą zrozumieć komentarze. Omów znaczenie jasnych i zwięzłych komentarzy w kodzie.
5. Napisz program z komentarzami, które zawierają odniesienia do źródeł zewnętrznych lub dokumentacji. Poproś kogoś innego o przeczytanie kodu i sprawdź, czy uznają dodatkowe zasoby pomocne. Omów znaczenie dostarczania dodatkowych zasobów dla czytników kodu.
6. Wybierz znany projekt open source i przeczytaj komentarze w kodzie. Omów różne style i poziomy komentowania używanego w projekcie oraz sposób, w jaki przyczyniają się do ogólnej czytelności kodu.
7. Napisz program z komentarzami, które obejmują wyjaśnienia decyzji projektowych lub kompromisów. Poproś kogoś innego o przeczytanie kodu i sprawdzi, czy uważają wyjaśnienia pomocne w zrozumieniu kodu. Omów znaczenie zapewnienia kontekstu i rozumowania za decyzjami kodowymi.