4 zasady dobrej dokumentacji

Niedawno rozmawiałam o dokumentacji kodu z juniorem, któremu mentoruję, i wymieniłam mu cztery zasady dobrej dokumentacji. Mój podopieczny był zaskoczony, że ktoś był w stanie to tak konkretnie i zwięźle przedstawić. Postanowiłam je więc rozpisać.

Dobra dokumentacja kodu musi zatem zawierać cztery następujące informacje:

• Cel: dlaczego dany kod (w postaci biblioteki, fragmentu kodu, metody lub klasy) został napisany
• Funkcja: co ten kod robi
• Forma: w jaki sposób kod osiąga to, co robi
• Zastosowanie: w jaki sposób kod może zostać użyty

W pozostałej części artykułu użyję przykładowej klasy PieChart, która została napisana w celu wyświetlania wykresu kołowego na ekranie.

Jest to dość prosta koncepcja zawierająca w sobie jedną funkcję, którą można wykorzystać na nowo.

Cel

Dlaczego stworzono klasę PieChart? W naszym przykładzie zawiera ona cały kod niezbędny do wyświetlenia wykresu kołowego użytkownikowi. W naszej aplikacji będziemy wyświetlać wiele wykresów kołowych, więc najlepiej będzie mieć dobrze napisaną klasę do ich obsługi. Celem tej klasy jest zatem łatwe kodowanie wykresów kołowych.

Ogólnie rzecz biorąc, cel jest najłatwiejszy do określenia i napisania. Co więcej, klasa po prostu została napisana, ponieważ istniała taka potrzeba. Co należy tu zrobić, to wyjaśnić tę potrzebę następnemu programiście. 

W ten sposób pomagasz zrozumieć, dlaczego jest to ważny element całego projektu lub biblioteki, a osoba ta będzie wiedzieć, jak używać go w swoim kodzie. Ponadto, ta część dokumentacji niekoniecznie musi być długa. 

Powinno się w niej także wymienić wszystkie założenia, które zostały przyjęte przy tworzeniu kodu. Tutaj możesz wymieniać alternatywy dla tego kodu, które mogłyby zadziałać, gdyby nie konkretne wcześniejsze wymagania.

CEL:

PieChart to klasa zawierająca funkcję wyświetlania wykresów kołowych.

Funkcja

Jest to wysokopoziomowy opis kodu. W naszym przykładzie kod pobiera dane użytkownika i wyświetla je jako wykres kołowy. Opis ten jest jednak dosyć lakoniczny i tak naprawdę jest jedynie duplikatem sekcji "Cel".

Musimy wyjaśnić, co robią wszystkie części klasy PieChart. Można to podzielić na sekcje i wyjaśnić, dostarczając tym samym dokumentację do fory. Jednak w przypadku złożonego kodu, najlepiej jest osobno opisać funkcję i użyte mechanizmy.

FUNKCJA:

PieChart pobiera dane użytkownika i konwertuje je na możliwy do wyświetlenia format, który jest następnie przedstawiany użytkownikowi. Wykresy kołowe są tworzone przy użyciu lokalnej biblioteki graficznej i opisane przy użyciu dostarczonych strings. Wykresy kołowe mogą być tworzone w dowolnym rozmiarze w granicach ekranu. Można je również umieścić w dowolnym miejscu na ekranie, o ile mieści się ono w jego granicach. Wykresy kołowe zostaną utworzone przy użyciu zestawu kolorów obliczonych w celu zapewnienia kontrastu między sekcjami. W razie potrzeby, można podać swoje kolory.

Forma

Teraz musimy przejść do szczegółów kodu. W tym miejscu wyjaśniamy wszystkie sztuczki, złożone algorytmy i założenia, które przyjmuje kod.

Nie każda metoda lub właściwość musi być indywidualnie udokumentowana, zwłaszcza jeśli jest opisowo nazwana i łatwa do ogarnięcia. Złożone metody i parametry metod powinny być jednak opisywane, szczególnie jeśli komentarze można zobaczyć w autozupełnianiu edytora.

Dokumentacja powinna być tutaj na takim poziomie, że gdyby ktokolwiek miał się jej przyjrzeć (lub gdybyś wrócił do niej za pół roku), nie miałby żadnych pytań. W tym przypadku, im dokładniejszy opis, tym lepiej

W tym miejscu musisz również wyjaśnić, dlaczego jeden algorytm został wybrany zamiast innego, zwłaszcza jeśli używany algorytm jest niestandardowy. Istnieje wiele standardowych praktyk dla większości rodzajów oprogramowania, a jeśli Twój kod będzie się od nich różnić, wyjaśnij, dlaczego i jak.

Wiem, jak bardzo my, programiści, lubimy wykorzystywać sprytne sztuczki w naszym kodzie; jeśli jednak tego nie udokumentujesz, nikt nie będzie wiedział, co się właśnie stało.

Poniżej znajduje się przykład dobrego komentarza dla jednej z metod naszej klasy.

FORMA:

/*
Ta metoda zawiera cały kod rysowania wykresu na ekranie. Spodziewa się promienia okręgu, współrzędnych środka, tablicy danych, kolorów i opisów pobranych z właściwości klasy. Bez nich metoda zwróci błąd.

Pętla rysowania: wyliczenie łuku z danych, narysowanie linii ze środka okręgu do punktu startu łuku, narysowanie łuku, narysowanie linii z punktu końca łuku do punktu środka okręgu, wypełnienie kolorem, stworzenie opisu, obrócenie go zgodnie z łukiem, narysowanie opisu.

Ta metoda zgłosi błąd w przypadku niepowodzenia.
*/

func DrawChart()

Zastosowanie

Na koniec musimy opisać, jak korzystać z kodu. W niektórych przypadkach jest to opcjonalne, ale tylko wtedy, gdy użycie jest oczywiste i łatwe do wywnioskowania. Zwykle dzieje się tak tylko w przypadku prostych metod.

Cała reszta powinna mieć opis zastosowania i, jeśli to możliwe, opis ten, powinien być umieszczony w komentarzu w taki sposób, aby edytory mogły go pokazać we wskazówkach autouzupełnienia, a biblioteki samo-dokumentujące mogły go bez trudu odczytać.

ZASTOSOWANIE:

PieChart.init(Array userData[], Array userColors[], Array descriptions[], double radius, point centerPoint)

userData to tablica wartości (double), która zostanie użyta do obliczenia procentowej części wykresu kołowego.

userColors to opcjonalna tablica kolorów pasująca jeden do jednego do każdej wartości.

descriptions to opcjonalna tablica łańcuchów znaków do wyświetlenia w obrębie każdego wycinka pasującego jeden do jednego do każdej wartości.

radius to promień wykresu kołowego.

centerPoint to środek wykresu kołowego przedstawiona jako punkt (double x, double y).

Piąta zasada: Fun

Zarówno pisanie, jak i czytanie dokumentacji, nie ma wiele wspólnego z zabawą. Czytanie może być informatywne, jeśli dokumentacja jest napisana poprawnie, ale często w wielu przypadkach ciężko przez nią przebrnąć. Lubię dodawać aspekt humorystyczny tam, gdzie mogę, i zachęcam do zrobienia tego samego. Czytelnik często docenia celowe gry słów lub żarty wynikające z kontekstu. Pamiętaj jednak o polityce, bo niektórzy pracodawcy krzywo na to patrzą.

Podsumowanie 

Robienie dobrej dokumentacji wiąże się z byciem dobrym programistą. Ta cecha jest często niedoceniania, dopóki dobra dokumentacja nie jest potrzebna. Zachęcam każdego programistę do dokumentowania swojego kodu, chociażby ze względu na zrozumienie tego, co się napisało. Gwarantuję jednak, że jeśli sumiennie piszesz dobrą dokumentację, Twoi współpracownicy Cię za to pokochają.