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

9

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?

Inżynier świata
źródło
1
Zależy to oczywiście w dużej mierze od tego, czy mówiono o złożoności matematycznej czy złożoności architektonicznej. Nie są w żaden sposób udokumentowane. Który to jest?
Edward Strange
2
powiązane: gdzie programista powinien wyjaśnić rozszerzoną logikę kodu? . Szczególnie podoba mi się podejście typu test-a-doc zasugerowane w jednej z odpowiedzi.
komar
1
@Gnat, dlaczego dzięki. Myślę, że ogólnie moja odpowiedź na to pytanie również zadziałałaby na to pytanie.
Mark Booth
@ MarkBooth racja, to była głównie twoja odpowiedź, o której myślałem, sugerując powiązane pytanie. Odpowiedź jest ogólnie dobra, ale chodzi o to, że testy szczególnie zadzwoniły, ponieważ użyłem jej raz dla jednej szczególnie skomplikowanej implementacji algorytmu
gnat

Odpowiedzi:

8

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.

Kirk Broadhurst
źródło
3

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.

Oleksi
źródło
0

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.

JeffO
źródło
1
„Jeśli jr. Dev będzie wymagane do utrzymania kodu ...” Z mojego doświadczenia lepiej jest po prostu założyć, że wszyscy czytający twoje komentarze to jr. dev. Jeśli nie są, to nie czytają twoich komentarzy. Nawet jeśli nie są jr. i wciąż czytają twoje komentarze, żargon i założenia prowadzą do nieporozumień. Wreszcie ... większość deweloperów, jak każda inna dziedzina znana człowiekowi, przeżywa życie, nie drażniąc się i nigdy tak naprawdę nie osiąga o wiele lepszego niż „jr”.
Edward Strange