Jak dokumentować niekoniecznie złożone struktury kodu?

Jeśli mam fragment kodu, który jest matematycznie lub strukturalnie dość złożony i nieredukowalnie, to jak miałbym udokumentować ten fragment kodu? W szczególności, w jaki sposób mogę zapewnić, że ktoś, kto może nie mieć umiejętności matematycznych lub architektonicznych, które rozumiem, może to zrozumieć z dokumentacji? Czy powinienem również dokumentować całą matematykę? Link do samouczka? Czy jakieś wizualne połączenie pomocy w przypadku złożonych struktur?

To naprawdę zależy od tego, jak skomplikowany jest kod i matematyka. Sam kod powinien - jak zawsze - być tak samo dokumentujący jak to tylko możliwe. Nazwij zmienne poprawnie, zaimplementuj metody logiczne i zwięzłe (zamiast mega-funkcji), dodaj odpowiednią dokumentację w odpowiednim miejscu (tj. Gdy nie jest oczywiste, co tak naprawdę robi kod).

Jeśli używasz nieoczywistego algorytmu, dodaj link do odwołania do źródła. Jest to rozsądna praktyka, ponieważ daje programistom bardzo szybki sposób na sprawdzenie, co robisz. Jak powiedziałem, jest to przydatne, jeśli jest to nieoczywisty, ale złożony algorytm. To powinno udowodnić, że (a) robisz coś, co ma sens, i (b) ktoś udowodnił, że to działa.

Dobrym przykładem jest praca, jaką wykonałem wokół dopasowywania tekstu rozmytego. Przeprowadziłem gruntowne badania nad algorytmami i wdrożyłem tak zwany „algorytm Smitha-Watermana” (który jest faktycznie używany do sekwencji DNA, ale ogólnie odnosi się do „dopasowania”). Zamiast więc implementować algorytm, znalazłem referencje online i zamieściłem link lub dwa. Jak wyżej, pokazuje to, że (a) mój algorytm pasuje do opublikowanego algorytmu oraz (b) algorytm został sprawdzony i wykazał, że działa.

Nie musi to jednak wyjaśniać, jak działa kod i co powinny robić różne klasy. Kiedy zaczniesz pisać „prawdziwą” dokumentację - przewodnik dla programistów dotyczący systemu - powinieneś wyjaśnić, co zrobiłeś i podać wystarczającą ilość informacji do przyszłego wsparcia. Moim zdaniem dokument ten powinien być czytelny dla osoby bez technicznej wiedzy; nie musi być „głupi”, ale powinien wykluczać żargon, a nie polegać na założonej wiedzy.

Komentarze dotyczące źródła są pierwszą rzeczą, którą powinieneś zrobić. Dzięki temu kod jest bezpośrednio połączony z dokumentacją. Jeśli dokumentacja jest bardzo skomplikowana, rozważ zamieszczenie tylko streszczenia w komentarzach, a następnie łącza do jakiegoś zewnętrznego dokumentu, który zawiera bardziej kompletny opis architektury / złożonego algorytmu. Jeśli jednak nie jest to zbyt skomplikowane, rozważ umieszczenie całej dokumentacji w jednym miejscu. Pozwoli to zmaksymalizować prawdopodobieństwo synchronizacji kodu / dokumentacji i odczytywania ich razem.

Dokumentuj kod w zakresie, w jakim potrzebuje go Twój zespół / firma. Jeśli jr. deweloper będzie musiał zachować kod, być może będziesz musiał szczegółowo opisać matematykę. Jest to decyzja kierownictwa i muszą dać ci niezbędny czas.

Nie sądzę, że musisz udokumentować kod tak bardzo, że bierzesz pod uwagę zamianę mniejszego programisty. Jeśli jest to problem, musisz mieć czas na udokumentowanie.

Nie powinieneś ich wyszukiwać w Internecie.