Metodologia dokumentowania istniejącej bazy kodu

35

Pracuję jako część zespołu nad istniejącą aplikacją, która nie ma wbudowanej dokumentacji ani dokumentacji technicznej. Pracując nad różnymi zgłoszeniami błędów dotyczących aplikacji, napisałem dla siebie coś w rodzaju ścieżki nawigacyjnej - numery błędów w różnych miejscach, aby następny programista mógł skorzystać z tego numeru błędu, aby zobaczyć, co się dzieje.

Moje pytanie brzmi zatem:

Jaka jest najbardziej wydajna metoda dokumentowania tego kodu? Czy powinienem dokumentować, dotykając obszaru (metoda wirusowa, jeśli chcesz), czy też powinienem dokumentować z każdej sekcji osobno, a nie podążać ścieżkami rozgałęziającymi się w inne obszary aplikacji? Czy powinienem wstawiać wbudowane komentarze tam, gdzie wcześniej nie istniały (z obawy, że w końcu mogę nie zidentyfikować, co robi kod)?

Jakiej metody użyłbyś do dokładnego i szybkiego udokumentowania dość dużej aplikacji, która nie ma istniejącej dokumentacji wbudowanej ani wbudowanych odniesień do dokumentacji zewnętrznej?

George Stocker
źródło
1
+1 Sposób zarządzania jest równie ważny, jak to zrobić.
1
Większość kodu, który widziałem, nie jest udokumentowana. Próbowałem wyczyścić kod innych ludzi i zostałem do niego wykrzyczany ORAZ to pojawiło się podczas mojej corocznej recenzji. Jeśli cały czas przebywasz na świecie lub nie obchodzi Cię, jak spędzasz 50 godzin pracy, z pewnością pytanie powinno brzmieć „Jak to zrobić?”. Czy jednak na pewno chcesz to zrobić? Wiele zależy od kultury firmy, od tego, jak bardzo chcą zwiększyć sprzedaż, jak dobrze rozumieją biznes związany z oprogramowaniem, ... jakiego języka i narzędzi używają. Dla C # istnieje fajne narzędzie o nazwie StyleCop, a także GhostDoc. Narzędzia istnieją, ale czasu jest mało.
Job
1
Czy zastanawiałeś się nad odpowiedzią na to pytanie? Jeśli nie szukasz naszych odpowiedzi, być może zaktualizujesz swoje pytanie. Z przyjemnością zaktualizuję moją odpowiedź, aby lepiej pasowała do twojego pytania.
Mark Booth

Odpowiedzi:

18

Dokumentowanie starszych baz kodu

Gorąco polecam przestrzeganie zasady scouta ze starszymi bazami kodu. Próba udokumentowania starszego projektu niezależnie od pracy nad nim nigdy się nie wydarzy.

Dokumentacja w kodzie

Najważniejszą rzeczą jest użycie funkcji dokumentacji w wybranym środowisku programistycznym, co oznacza pydoc dla komentarzy w python, javadoc w java lub xml w języku C #. Ułatwiają one pisanie dokumentacji w tym samym czasie, co pisanie kodu.

Jeśli polegasz na powrocie i dokumentowaniu rzeczy później, możesz nie poradzić sobie z tym, ale jeśli zrobisz to podczas pisania kodu, to, co należy udokumentować, będzie świeże w twoich myślach. C # ma nawet opcję wydania ostrzeżenia o kompilacji, jeśli dokumentacja XML jest niekompletna lub niezgodna z rzeczywistym kodem.

Testy jako dokumentacja

Innym ważnym aspektem jest dobra integracja i testy jednostkowe.

Często dokumentacja koncentruje się na tym, co klasy i metody robią w oderwaniu, pomijając ich wspólne użycie w celu rozwiązania problemu. Testy często umieszczają je w kontekście, pokazując, jak współdziałają ze sobą.

Podobnie testy jednostkowe często wyraźnie wskazują na zależności zewnętrzne, za pomocą których należy wykpić elementy .

Uważam również, że korzystając z programowania opartego na testach piszę oprogramowanie, które jest łatwiejsze w użyciu, ponieważ używam go od samego początku. Przy dobrej strukturze testowania ułatwienie testowania kodu i ułatwienie korzystania z niego to często to samo.

Dokumentacja na wyższym poziomie

Wreszcie jest co zrobić z poziomem systemu i dokumentacją architektoniczną. Wielu opowiada się za pisaniem takiej dokumentacji na wiki lub za pomocą Worda lub innego edytora tekstu, ale dla mnie najlepszym miejscem na taką dokumentację jest także kod, w formacie zwykłego tekstu, który jest przyjazny dla systemu kontroli wersji.

Podobnie jak w przypadku dokumentacji w kodzie, jeśli przechowujesz dokumentację wyższego poziomu w repozytorium kodu, istnieje większe prawdopodobieństwo, że będziesz ją aktualizować. Korzyścią jest również to, że po wyciągnięciu wersji XY kodu otrzymujesz również wersję XY dokumentacji. Ponadto, jeśli używasz formatu przyjaznego dla VCS, oznacza to, że można łatwo rozgałęziać, różnicować i scalać, podobnie jak kod.

Bardzo lubię pierwszą , ponieważ łatwo jest z niej tworzyć zarówno strony HTML, jak i dokumenty PDF, i jest o wiele bardziej przyjazna niż LaTeX , ale wciąż może zawierać wyrażenia matematyczne LaTeX, gdy są potrzebne.

Mark Booth
źródło
4
+1 dla harcerza, ale więcej, ponieważ jesteś jedyną osobą, która wspomina o testach. Testy potwierdzają twoje założenia dotyczące kodu, są lingua franca dla programistów i nigdy się nie synchronizują (pod warunkiem, że będziesz je przekazywał).
kamera douszna
16

Podchwytliwe pytanie. Zasadniczo użyłbym metody „refaktoryzacji”, którą przekształciłbym w „jeśli dotkniesz kodu, udokumentuj go”.

Ale żeby być precyzyjnym; w miarę pojawiania się problemów i gdy musisz zaznajomić się z kodem, aby naprawić występujące błędy, powiedziałbym, że powinieneś użyć tej znajomości do pisania komentarzy na temat tego kodu; w istocie motywacja do naprawienia błędu w tym momencie zmusiła cię do zaznajomienia się z kodem na tyle, aby móc go udokumentować. Z tego powodu ostrożnie podążam za niepowiązanymi gałęziami LUB dokumentując niepowiązane funkcje, ponieważ w tym momencie, jeśli nie wykonujesz aktywnych testów kodu (w celu zweryfikowania naprawy błędu), trudno jest być całkowicie pewny, że dokładnie rozumiesz, co robi kod i dlaczego. (Nie wchodzę w problem, że może być również trudno dokładnie ustalić, co i dlaczego kod robi to, co robi, nawet podczas testowania poprawki błędu;

Takie podejście powinno dążyć do maksymalizacji dokładności, z poświęceniem ogólnej prędkości, ale nie powinno wpływać na potrzebę zbytniego utrzymywania kodu w tym samym czasie. Jeśli twoje obowiązki związane z usuwaniem błędów są niewielkie, możesz zaryzykować na „nieznanym terytorium” i rozpocząć dokumentowanie tam, ale jeśli (jak większość z nas) nie możesz znaleźć wystarczającej ilości dnia, aby zarówno naprawić kod, jak i udokumentować go, to dobry kompromis.

Należy również zauważyć jedno; powinieneś mieć dobrą zewnętrzną dokumentację. Mówisz, że twój kod nie zawiera odniesień do dokumentacji zewnętrznej; Mam jednak nadzieję, że taka dokumentacja zewnętrzna istnieje. Jeśli nie, tak naprawdę uczynię pisanie tej zewnętrznej dokumentacji twoim priorytetem; coś na poziomie specyfikacji funkcjonalnej jest, moim zdaniem, absolutnie kluczowe dla wszystkich dużych projektów oprogramowania. Powodem jest to, że specyfikacje funkcjonalne lub dokumentacja wysokiego poziomu tego formularza mogą pomóc w zapobieganiu „pełzaniu funkcji” lub „dryfowaniu funkcji” w jakimkolwiek oprogramowaniu; przesunięcie cech (w szczególności) może być destrukcyjne dla dokumentacji, ponieważ może spowodować, że dokumentacja stanie się nieaktualna. (Definiuję pełzanie funkcji jako stopniowe (i irytujące) dodawanie funkcji do oprogramowania; cecha dryfz drugiej strony zestaw działań, które oprogramowanie powoli zmienia w czasie. Pełzanie funkcji jest DODATKOWE, tzn. Zazwyczaj obejmuje zwiększenie zestawu funkcjonalności oprogramowania; dryf cech jest natomiast sumą zerową; jeden po drugim definiuje się jeden element funkcjonalności krawędzi, aby zrobić coś innego, dopóki oprogramowanie nie zrobi czegoś zupełnie innego niż pierwotnie zamierzano. Dryft cech jest rzadki, ale ŚMIECI dla dokumentacji.)

Paul Sonier
źródło
Czy możesz powiedzieć więcej o przesunięciu funkcji? Rozumiem, że zabójcza dla dokumentacji; ponieważ dokumentacja i oprogramowanie mogą się różnić. Ale czy znoszenie funkcji jest czymś, czego należy unikać? Pozytywną stroną jest to, że oprogramowanie ewoluuje wraz ze zmieniającymi się wymaganiami. Możemy zaprojektować nasz projekt, aby uwzględnić dryf funkcji: architektura oddolna jest suppostą, która prowadzi do wymiennego oprogramowania: na przykład Emacs i TeX mają większą architekturę. Jakie są złe aspekty zmiany funkcji oprogramowania?
Kasper van den Berg
4

Jedna aplikacja, którą współtworzyłem w ciągu dwóch lat, miała poważny brak dokumentacji. W pewnym momencie stało się jasne, że przekażemy aplikację innemu deweloperowi, który będzie ją utrzymywał od tego momentu, więc musieliśmy udokumentować kod.

Aby poradzić sobie z gigantycznym zakresem procesu dokumentacji, starałem się dokumentować cały kod w określonej funkcji lub części aplikacji w danym dniu. Nie miałem żadnego szczególnego wzorca, ale nalegałem na robienie czegoś każdego dnia i uzyskanie poczucia ukończenia przez codzienne dokumentowanie całego pliku lub sekcji aplikacji.

Udokumentowanie całej aplikacji zajęło miesiące, ale w ciągu pół godziny (maksymalnie) dziennie nigdy tak naprawdę nie wpisało się w harmonogram projektu i uniknęło wielu problemów związanych z dokumentowaniem.

Wykorzystaliśmy dokumentację XML w języku C #, która dostarczyła wystarczającą liczbę funkcji i struktur, aby ułatwić dokumentację. Nawet jeśli nie dokumentujesz aplikacji C #, wzorzec krótkiego podsumowania, po którym następują uwagi, był bardzo użyteczny.

NigelTufnel
źródło
3

Dokumentowałbym jak dodałem / zmodyfikowałem kod. Poza tym dokumentowałbym również publiczne interfejsy API lub interfejsy między modułami. Jeśli udokumentujesz cały kod, możesz nie zobaczyć ROI za spędzony czas. Przydatne może być użycie czegoś takiego jak wiki do organizowania zewnętrznej dokumentacji podczas jej opracowywania. Najbardziej użytecznym dokumentem, do którego odwoływałem się podczas mojego ostatniego projektu, był dokument architektury. Zawierał informacje o zastosowanych technologiach i zapewniał ogólny widok warstw aplikacji.


źródło
2

Użyłbym komentarzy Doxygen. Doxygen ma więcej formatów wyjściowych niż większość innych darmowych formatów i jest łatwy do nauczenia.

Możesz nawet rozważyć zatrudnienie kontrahenta, aby to zrobić, ponieważ niektórzy z nas zarabiają na to. Jednak przy tym wyborze nadal musisz zobowiązać się do przejrzenia dokumentów.

Inną popularną techniką jest przypisywanie nowego programisty do dokumentowania kodu. Następnie niech każda nowa osoba przejdzie przez to, gdy osiągnie prędkość. Pamiętaj, że niektórzy deweloperzy uważają to za uzyskanie kanału korzeniowego - konieczne tylko w bezpośrednich przypadkach, LOL.

SnoopDougieDoug
źródło
1

Zanim zaczniesz dokumentować cokolwiek, opracuj standard. Może to być tak proste, jak zapisanie kilku wierszy nad nagłówkiem funkcji lub klasy do czegoś bardziej oficjalnego i pełnego (np. Javadoc). Aby ktokolwiek mógł sprawdzić kod, jego dokumentacja musi spełniać ten standard.

To, co znalazłem, działa dobrze, to dodawanie dobrze napisanych komentarzy przed nagłówkiem funkcji do funkcji, które wcześniej utworzyłem, i które nie były dokumentowane, oraz dodawanie wbudowanych komentarzy do wszystkiego, co dodałem. Chcesz uniknąć dokumentowania kodu, którego nie dotknąłeś. Gorzej jest mieć złe komentarze niż brak komentarzy, a jeśli dokumentujesz to „szybko”, prawdopodobnie napiszesz złe komentarze.


źródło