Jak zrobić dokumentację dla kodu i dlaczego oprogramowanie (często) jest słabo udokumentowane?

Istnieje kilka dobrych przykładów dobrze udokumentowanego kodu, takich jak Java Java API. Ale wiele kodu w projektach publicznych, takich jak git i projekty wewnętrzne firm, jest słabo udokumentowane i niezbyt przyjazne dla początkujących.

Na wszystkich etapach rozwoju oprogramowania miałem do czynienia ze słabo udokumentowanym kodem. Zauważyłem następujące rzeczy -

1. Brak lub brak komentarzy w kodzie.
2. Nazwy metod i zmiennych nie są samoopisujące.
3. Dokumentacja tego, jak kod pasuje do systemu lub procesów biznesowych, jest niewielka lub nie ma jej wcale.
4. Zatrudnianie złych programistów lub nie mentoring dobrych. Nie potrafią napisać prostego i czystego kodu. Dlatego jest to trudne lub niemożliwe dla każdego, w tym dla programisty, do udokumentowania kodu.

W rezultacie musiałem przejść dużo kodu i porozmawiać z wieloma ludźmi, aby się czegoś nauczyć. Czuję, że marnuje to czas każdego. Powoduje to również potrzebę sesji KT / transferu wiedzy dla nowych uczestników projektu.

Dowiedziałem się, że dokumentacja nie otrzymuje uwagi, na którą zasługuje, z następujących powodów:

1. Lenistwo.
2. Programiści nie lubią robić nic poza kodowaniem.
3. Bezpieczeństwo pracy. (Jeśli nikt nie może łatwo zrozumieć twojego kodu, być może nie będziesz łatwo go wymienić).
4. Trudne terminy pozostawiają niewiele czasu na dokumentację.

Zastanawiam się więc, czy istnieje sposób na zachęcanie i egzekwowanie dobrych praktyk dokumentacyjnych w firmie lub projekcie. Jakie strategie należy zastosować do stworzenia porządnej dokumentacji systemów i kodu każdego projektu, niezależnie od jego złożoności? Czy są jakieś dobre przykłady tego, kiedy potrzebna jest minimalna dokumentacja lub jej brak?

IMHO, uważam, że powinniśmy mieć przegląd dokumentacji po dostarczeniu projektu. Jeśli nie jest to proste, zwięzłe, ilustracyjne i przyjazne dla użytkownika, deweloper lub inżynier dokumentacji technicznej ponosi za to odpowiedzialność i musi go naprawić. Nie oczekuję też, że ludzie stworzą ryzę dokumentacji, nie mam nadziei, że będzie przyjazny dla użytkownika, tak jak w przypadku pierwszych książek, ale spodziewam się, że wyeliminuje on potrzebę godzin analiz i marnotrawstwa sesji KT.

Czy istnieje sposób na zakończenie lub złagodzenie tego szaleństwa? Być może „rozwój oparty na dokumentach”?

Jak udokumentować kod?

Masz już podpowiedź: spójrz na dokumentację Java API.

Mówiąc bardziej ogólnie, nie ma unikalnego zestawu zasad, które mają zastosowanie do każdego projektu. Kiedy pracuję nad kluczowymi dla biznesu projektami na dużą skalę, dokumentacja nie ma nic wspólnego z tą, którą napisałbym dla małej biblioteki open source, która z kolei nie ma nic wspólnego z dokumentacją mojego osobistego projektu na średnią skalę .

Dlaczego wiele projektów open source nie jest dobrze udokumentowanych?

Ponieważ większość projektów o otwartym kodzie źródłowym są tworzone przez ludzi, którzy przyczyniają się do tych projektów, ponieważ jest to zabawne. Większość programistów i programistów uważa, że pisanie dokumentacji nie jest wystarczająco zabawne, aby robić to za darmo.

Dlaczego wiele projektów z zamkniętym źródłem nie jest dobrze udokumentowanych?

Ponieważ kosztuje ogromną sumę (1) napisanie dobrej dokumentacji i (2) utrzymanie jej.

1. Bezpośredni koszt (koszt sporządzenia dokumentacji) jest wyraźnie widoczny dla interesariuszy: jeśli Twój zespół poprosi o poświęcenie kolejnych dwóch miesięcy na dokumentowanie projektu, musisz zapłacić dwa dodatkowe miesiące wynagrodzenia.

2. Koszt długoterminowy (koszt utrzymania dokumentacji) staje się zauważalny również dość łatwo dla menedżerów i jest często pierwszym celem, gdy muszą obniżyć koszty lub skrócić opóźnienia. Powoduje to dodatkowy problem nieaktualnej dokumentacji, która szybko staje się bezużyteczna, a jej aktualizacja jest niezwykle kosztowna.

3. Z drugiej strony trudno jest zmierzyć długoterminowe oszczędności (oszczędności wynikające z niepotrzebnego marnowania kilku dni na zapoznanie się ze starszym kodem tylko po to, aby zrozumieć podstawową rzecz, którą powinno się udokumentować lata temu), co potwierdza odczucia niektórych menedżerów pisanie i utrzymywanie dokumentacji to strata czasu.

Często obserwuję, że:

1. Na początku zespół chętnie dużo dokumentuje.

2. Z czasem presja terminów i brak zainteresowania sprawiają, że utrzymanie dokumentacji jest coraz trudniejsze.

3. Kilka miesięcy później nowa osoba, która dołącza do projektu, praktycznie nie może korzystać z dokumentacji, ponieważ w ogóle nie odpowiada ona rzeczywistemu systemowi.

4. Zauważając to, kierownictwo obwinia programistów za brak obsługi dokumentacji; programiści proszą o zaktualizowanie go przez kilka tygodni.

   • Jeśli kierownictwo przyzna na to kilka tygodni, cykl się powtarza.

   • Jeśli kierownictwo odmówi, na podstawie wcześniejszych doświadczeń, tylko pogorszy złe doświadczenia, ponieważ produkt nie ma dokumentacji, ale kilka miesięcy spędzono na jej pisaniu i utrzymywaniu.

Dokumentacja powinna być ciągłym procesem, podobnie jak testowanie. Spędź tydzień na kodowaniu kilku tysięcy LOC, a powrót do testów i dokumentacji jest bardzo, bardzo bolesny.

Jak zachęcić zespół do napisania dokumentacji?

Podobnie jak sposoby zachęcania ludzi do pisania czystego kodu, regularnego refaktoryzowania, używania wzorców projektowych lub dodawania wystarczającej liczby testów jednostkowych.

• Dawaj dobry przykład. Jeśli napiszesz dobrą dokumentację, twoje pary też mogą zacząć to robić.

• Wykonuj systematyczne przeglądy kodu, w tym formalne przeglądy kodu mające na celu sprawdzenie dokumentacji.

• Jeśli niektórzy członkowie zespołu są szczególnie antypatyczni wobec dobrej dokumentacji (lub dokumentacji), przedyskutuj z nimi ten temat prywatnie, aby zrozumieć, jakie są przeszkody, które uniemożliwiają im napisanie lepszej dokumentacji. Jeśli obwiniają brak czasu, widzisz źródło problemów.

• Uczyń obecność lub brak dokumentacji mierzalnymi przez kilka tygodni lub miesięcy, ale nie skupiaj się na tym. Na przykład możesz zmierzyć liczbę wierszy komentarzy na LOC, ale nie rób z tego stałego pomiaru, w przeciwnym razie programiści zaczną pisać długie, ale pozbawione znaczenia komentarze, aby pozbyć się niskich wyników.

• Użyj grywalizacji. Towarzyszy temu poprzedni punkt.

• Użyj wzmocnienia dodatniego / ujemnego .

• (Zobacz komentarz SJuan76 ) Traktuj brak komentarzy jako błędy. Na przykład w Visual Studio można zaznaczyć opcję generowania dokumentacji XML. Jeśli sprawdzisz również, czy wszystkie ostrzeżenia są traktowane jako błędy, brak komentarza na szczycie klasy lub metody zatrzyma kompilację.

  Jeśli chodzi o trzy poprzednie punkty, tego należy używać ostrożnie. Używałem go przez pewien czas ze szczególnie trudnym zespołem początkujących programistów, a skończyło się na takich komentarzach zgodnych z StyleCop:

    /// <summary>
    /// Gets or sets the PrimaryHandling.
    /// </summary>
    public Workflow PrimaryHandling { get; set; }

które nie były szczególnie pomocne.

Pamiętaj: nic zautomatyzowanego nie pomoże ci znaleźć złych komentarzy, gdy programiści chcą się z tobą pograć . Pomogą w tym tylko recenzje kodu i inne ludzkie czynności.

Czy są jakieś dobre przykłady tego, kiedy potrzebna jest minimalna dokumentacja lub jej brak?

Dokumentacja wyjaśniająca architekturę i projekt nie jest potrzebna:

• Dla prototypu

• W przypadku osobistego projektu napisanego w ciągu kilku godzin w celu wykonania zadania, mając pewność, że ten projekt nie będzie już dłużej utrzymywany,

• W przypadku każdego projektu, w którym jest to oczywiste, biorąc pod uwagę jego niewielki rozmiar w połączeniu ze szczególnie czystym kodem, poświęcisz więcej czasu na pisanie dokumentacji niż wszyscy przyszli opiekunowie badający kod.

Dokumentacja w kodzie (komentarze do kodu) nie jest potrzebna według niektórych programistów, gdy kod jest samodokumentujący. Dla nich obecność komentarzy, z wyjątkiem rzadkich przypadków, nie jest dobrym znakiem, ale znakiem, że kod nie został wystarczająco zreformowany, aby był przejrzysty bez potrzeby komentowania.

Uważam, że po dostarczeniu projektu powinniśmy przejrzeć dokumentację.

Jeśli Twój projekt jest dostarczany co najmniej raz w tygodniu, jest to właściwy sposób. Jeśli Twój projekt nie jest sprawny i jest dostarczany w odstępach sześciomiesięcznych, zrób więcej regularnych recenzji.

Myślę, że należy wprowadzić rozróżnienie między komentarzami a dokumentacją. Chociaż komentarze mają charakter opisowy, nie są spójne, są rozrzucone po całym kodzie. Komentarze nigdy nie powinny rekompensować kodu, który nie jest wystarczająco samoopisujący się, zamiast tego powinno sugerować innym programistom trudne fragmenty.

To, czy kod powinien zostać udokumentowany, zależy od skali projektu. Na pewno są ludzie, którzy wierzą, że wszystko powinno być udokumentowane, i wydaje się, że łatwo to uzasadnić, ponieważ kto ośmieliłby się sprzeciwić dokumentowaniu wiedzy? Na szczęście tworzenie oprogramowania nie jest nauką, a świat się nie zawali, jeśli szczegóły stojące za twoim małym programem staną się niejasne. Jeśli chodzi o profesjonalne oprogramowanie do użytku wielu programistów, tak, oczywiście powinieneś udokumentować swój kod. Ale jeśli jesteś w stanie kodować na tym poziomie, to oczywiście o tym wiesz.

tl; dr

Jeśli chcesz, aby każdy projekt był dobrze udokumentowany, to pytasz za dużo.