Metodologia dokumentowania istniejącej bazy kodu

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?

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.

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.)

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.

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.

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.

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.