Każdy programista wie, że umieszczanie komentarzy w kodzie źródłowym aplikacji jest nie tylko elementem dobrej praktyki, ale także często wymogiem. Często jednak nie ma na to czas lub jest go zbyt mało. W domowych czy firmowych labach często w ogóle nie zawracamy sobie tym głowy. Jednak nawet gdy piszemy aplikację lub playbook tylko dla siebie warto zadbać o choćby minimalną jego dokumentację, a komentarze zawarte w kodzie źródłowym przydadzą się, jeżeli będziemy chcieli go wykorzystać potem w innym projekcie.
Dokumentacja i komentarze mają znaczenie
Wszyscy dobrze wiemy, jak duże znaczenie ma dobrze prowadzona dokumentacja infrastruktury czy konfiguracji. Podobnie jest, gdy piszemy programy czy skrypty. Komentarze zawarte bezpośrednio w kodzie pozwalają innym programistom zrozumieć, co wskazany fragment kodu robi, lub co z założenia miał robić. Nam samym pozwalają na przypomnienie sobie tego, w jaki sposób zaimplementowaliśmy jakąś funkcjonalność lub dlaczego użyliśmy takiej, a nie innej konstrukcji semantycznej w kodzie źródłowym.
Sam się ostatnio przekonałem o tym, że nawet w instalacjach laboratoryjnych nie warto odpuszczać sobie tworzenia dokumentacji i dodawania komentarzy w kodzie. Odgrzebałem stworzony półtora roku temu projekt playbooka w Ansible, gdyż chciałem z niego skorzystać. Jednak okazało się, że wymaga on podania różnych parametrów pracy i odpowiedniego manipulowania rolami, poza tym zawierał w sobie trochę testowych zadań, które nie powinny być wykonane. Niestety, ponieważ nie umieściłem w kodzie żadnych komentarzy, a sam projekt nie zawierał nawet najprostszej dokumentacji, straciłem trochę czasu, krok po kroku analizując jego działanie. Musiałem też z niego wyczytać jakie parametry muszę dodatkowo uruchamiając playbooka przekazać do Ansible. Straciłem na to trochę czasu.
Komentarze w Ansible
Chyba każdy język programowania pozwala na umieszczanie w kodzie źródłowym komentarzy. Są one oznaczone w specjalny sposób. Przykładowo pojedyncza linia komentarza w C czy C++ zaczyna się znakami //. Jeżeli chcemy wstawić cały blok składający się z wielu linii, to umieszczamy go pomiędzy znacznikami /* oraz */. W skryptach powłoki Linuksa czy w PowerShellu linię komentarza zaczynamy znakiem #. Elementy kodu źródłowego oznaczone jako komentarz są przez kompilator czy interpreter po prostu ignorowane. Środowiska programistyczne wykryte linie czy bloki komentarza dla przejrzystości kodu zawsze oznaczają dedykowanym kolorem czcionki.
W Ansible, aby oznaczyć daną linię jako komentarz rozpoczynamy ją znakiem #. Przykładowo:
# To jest linia komentarze
- name: Zainstaluj Dockera
apt:
name: [ docker-ce docker-ce-cli ]
# To też jest linia komentarza, ale z wcięciem
state: latest
update_cache: no
become: yes
become_user: root
# To też jest komentarz
become_method: sudo Wszystkie te trzy linie zostaną przez Ansible zignorowane, ale nam pozwolą na opisanie na przykład tego, co dane zadanie robi, albo dlaczego ustawiliśmy wartość wskazanego parametru tak, a nie inaczej.
Dokumentacja projektu
Nieco inną funkcję pełnią zewnętrzne pliki, które stanowią dokumentację całego projektu lub jego fragmentu. Zawieramy w nich informacje o sposobie uruchamiania aplikacji czy playbooka, przekazywanych parametrów czy wymaganych do poprawnego działania bibliotek. Możemy tam też umieszczać przykłady wywołania playbooka albo odnośniki do zewnętrznych stron.
Dokumentację projektu może stanowić jeden lub więcej zwykłych plików tekstowych. Na dłuższą metę są one jednak dość nieczytelne, gdyż brakuje im nawet podstawowego formatowania tekstu. Dlatego obecnie przyjętym standardem jest Markdown Language. Opiera się on na plikach tekstowych, lecz dzięki specjalnym markerom pozwala na proste formatowanie wyświetlanego tekstu. Zazwyczaj tego typu pliki otwieramy w przeglądarce internetowej. Markdown Language jest używany powszechnie w GitHub, GitLab czy innych narzędziach do grupowej pracy nad kodem.
Pliki dokumentacji w Markdown Language mają rozszerzenie .md. Nie ma jednego standardu gdzie w strukturze projektu je umieszczać albo jak się nazywać. Przyjęło się jednak, że podstawowy plik dokumentacji ma nazwę README.md i znajduje się w głównym folderze projektu. Wspomniane już systemy pracy grupowej domyślnie szukają tego pliku, by wyświetlić go jako element strony głównej projektu. W przypadku gdy nasz projekt składa się z definicji wielu ról, to plik README.md umieszczamy w głównym katalogu roli. Zawierać on powinien opis związany ze wskazaną rolą.
# Nagłówek Powyżej widzisz prosty nagłówek pierwszego rzędu. Sam tekst możesz w prosty sposób formatować dodając **pogrubienie**, *pochylenie* albo ~~przekreślenie~~. ## Nagłówek drugiego pozomu ### Nagłówek trzeciego poziomy #### Nagłówek czwartego poziomu ##### Nagłówek piątego poziomu A co powiecie na cytat? > To jest cytat A tak tworzymy listy - Pierwszy - Drugi W dokumencie możemy zawrzeć także odnośniki, na przykład do [Szkoły DevNet](https://szkoladevnet.pl/)
Markdown Language jest nieco podobny do HTML-a, oczywiście pozbawiony wszystkich zaawansowanych funkcji. Skupiamy się na przekazie, formatując jedynie w podstawowym zakresie jego warstwę estetyczną. Definiować możemy między innymi nagłówki dwóch poziomów, tekst pogrubiony, pochylony czy przekreślony, operować na listach numerowanych i nienumerowanych. Bardzo przystępny opis oraz przykład zastosowania formatowania znajdziemy na przykład na Wikipedii.
