Istnieje kilka dobrych przykładów dobrze udokumentowanego kodu, na przykład java api. Jednak wiele kodów w projektach publicznych, takich jak git i wewnętrzne projekty firm, jest słabo udokumentowanych i niezbyt przyjaznych dla nowych użytkowników.

We wszystkich moich pracach związanych z tworzeniem oprogramowania miałem do czynienia ze słabo udokumentowanym kodem. Zauważyłem następujące rzeczy –

  1. Niewiele lub brak komentarzy w kodzie.
  2. Nazwy metod i zmiennych nie opisują się same.
  3. Dokumentacja dotycząca tego, jak kod pasuje do systemu lub procesów biznesowych, jest niewielka lub nie ma jej wcale.
  4. Zatrudnianie złych programistów lub brak mentoringu dla dobrych. Nie potrafią napisać prostego i czystego kodu. Dlatego też udokumentowanie kodu przez nikogo, łącznie z programistą, jest trudne lub niemożliwe.

W rezultacie musiałem przejść przez wiele kodować i rozmawiać z wieloma ludźmi, aby się czegoś nauczyć. Czuję, że to marnuje czas każdego. Stwarza również potrzebę sesji transferu KT / wiedzy dla nowicjuszy w projekcie.

Dowiedziałem się, że dokumentacji nie poświęca się uwagi, na jaką zasługuje, z następujących powodów:

  1. Lenistwo.
  2. Deweloperzy nie lubią robić niczego poza kodem.
  3. Bezpieczeństwo pracy. (Jeśli nikt nie będzie w stanie łatwo zrozumieć Twojego kodu, możesz nie być łatwo wymienny).
  4. Trudne terminy pozostawiają niewiele czasu na udokumentowanie.

Zastanawiam się więc, czy istnieje sposób, aby zachęcić do dobrych praktyk dokumentacyjnych w firmie lub projekcie i je egzekwować. Jakie są strategie do tworzenia porządnej dokumentacji dla systemów i kodu dowolnego projektu, niezależnie od jego złożoności? Czy są jakieś dobre przykłady, kiedy minimalna dokumentacja jest potrzebna lub nie jest potrzebna?

IMHO, czuję, ż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, to deweloper lub inżynier dokumentacji technicznej ponosi za to odpowiedzialność i musi to naprawić. Nie oczekuję, że ludzie będą robić mnóstwo dokumentacji, Nie mam nadziei, że będzie on przyjazny dla użytkownika, jak w książkach Head First, ale spodziewam się, że wyeliminuje potrzebę godzin analiz i marnotrawnych sesji KT.

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

Komentarze

  • Jest jeszcze jeden powód, dla którego często brakuje odpowiedniej dokumentacji: bardzo trudno jest napisać dobrą dokumentację, która nie ' t tylko parafrazuje kod w języku angielskim, ale opisuje dlaczego kod został zaprojektowany / napisany w ten sposób. Potrzeba tych informacji staje się oczywista dopiero po kilku miesiącach, po ich zapisaniu.
  • Kolejny poważny powód: wielu programistów używa angielskiego jako drugiego języka i / lub źle pisze po angielsku . Możesz po prostu zmusić ich do napisania jednej linijki dla metody, ale jeśli potrzebujesz dobrej dokumentacji, lepiej przygotuj się na zapłacenie za nią i zatrudnienie specjalistów, którzy to zrobią.

Odpowiedź

Jak udokumentować kod?

Masz już wskazówkę: zobacz, jak udokumentowano interfejs Java API.

Ogólnie rzecz biorąc, nie ma unikalnego zestawu reguł, które mają zastosowanie do każdego projektu. Kiedy pracuję nad krytycznymi dla biznesu projektami na dużą skalę, dokumentacja nie ma nic wspólnego z tą, którą napisałbym dla małej biblioteki open source, co z kolei nie ma nic wspólnego z dokumentacją mojego osobistego projektu średniej skali .

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

Ponieważ większość projektów open source jest tworzonych przez ludzi, którzy biorą udział w tych projektach, ponieważ jest to zabawne. Większość programistów i programistów uważa że pisanie dokumentacji nie jest wystarczająco zabawne , aby wykonywać je za darmo.

Dlaczego wiele projektów o zamkniętym kodzie źródłowym nie są dobrze udokumentowane?

Ponieważ (1) napisanie dobrej dokumentacji i (2) jej utrzymanie kosztuje ogromne pieniądze.

  1. Natychmiastowe koszt (koszt napisania dokumentacji) jest wyraźnie widoczny dla interesariuszy: jeśli Twój zespół poprosi o spędzenie kolejnych dwóch miesięcy na dokumentowaniu projektu, do zapłacenia są dwa dodatkowe miesiące wynagrodzenia.

  2. Lo Koszt terminowy (koszt utrzymania dokumentacji) staje się również dość łatwy do zauważenia dla menedżerów i często jest pierwszym celem, kiedy muszą obniżyć koszty lub skrócić opóźnienia. Powoduje to dodatkowy problem z przestarzałą dokumentacją, która szybko staje się bezużyteczna i jest niezwykle kosztowna w aktualizacji.

  3. Oszczędności długoterminowe (oszczędności wynikające z braku konieczności marnowania kilku dni na badanie stary kod tylko po to, aby zrozumieć podstawową rzecz, która powinna była zostać udokumentowana lata temu) są z drugiej strony trudne do zmierzenia, co utwierdza niektórych menedżerów w przekonaniu, że pisanie i utrzymywanie dokumentacji to strata czasu.

Często obserwuję, że:

  1. Na początku zespół chce dużo dokumentować.

  2. Z biegiem czasu presja terminów i brak zainteresowania sprawiają, że prowadzenie dokumentacji staje się 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, kierownictwo obwinia programistów za nieprzechowywanie dokumentacji; programiści proszą o poświęcenie kilku tygodni na aktualizację.

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

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

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

Jak zachęcić zespół do pisania Dokumentacja?

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

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

  • Dokonuj systematycznych przeglądów kodu, w tym formalnych przeglądów kodu ukierunkowanych na sprawdzenie dokumentacji.

  • Jeśli niektórzy członkowie zespołu są szczególnie przeciwni dobrej dokumentacji (lub w ogóle dokumentacji), przedyskutuj z nimi ten temat na osobności, aby zrozumieć, jakie przeszkody uniemożliwiają im pisanie lepszej dokumentacji. Jeśli obwiniają brak czasu, widzisz źródło problemów.

  • Dopilnuj, aby obecność lub brak dokumentacji było mierzalne przez kilka tygodni lub miesięcy, ale nie skoncentruj się na tym. Na przykład możesz zmierzyć liczbę wierszy komentarzy na LOC, ale nie rób tego na stałe, w przeciwnym razie programiści zaczną pisać długie, ale bezsensowne komentarze, aby pozbyć się niskich wyników.

  • Korzystaj z grywalizacji. To idzie w parze z poprzednim punktem.

  • Użyj pozytywnego / negatywnego wzmocnienia .

  • (Patrz komentarz SJuan76 ). Potraktuj brak komentarzy jako błędy. Na przykład w programie 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 górze klasy lub metody zatrzyma kompilację.

    Podobnie jak w trzech poprzednich punktach, ten powinien być użyty z ostrożnością. Używałem go przez jakiś czas ze szczególnie trudnym zespołem początkujących programistów i skończyło się na zgodnych ze StyleCop komentarzach: 

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

które były, hm …, niezbyt pomocne.

Pamiętaj: nic zautomatyzowanego nie pomoże Ci wskazać złych komentarzy, gdy programiści chcą się z tobą bawić . Tylko kod recenzje i inne ludzkie zadania pomogą.

Czy są jakieś dobre przykłady sytuacji, gdy minimalna dokumentacja jest potrzebna lub nie jest wymagana?

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

  • W przypadku prototypu

  • W przypadku osobistego projektu napisanego w ciągu kilku godzin w celu wykonania zadania, przy jednoczesnej pewności, że ten projekt nie będzie już dłużej obsługiwany,

  • W przypadku każdego projektu, w którym jest to oczywiste, biorąc pod uwagę rozszerzenie niewielki rozmiar, w połączeniu z wyjątkowo czystym kodem, że spędzisz więcej czasu na pisaniu dokumentacji niż wszyscy przyszli opiekunowie badający kod.

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

Uważam, że powinniśmy mieć przegląd dokumentacji po dostarczeniu projektu.

Jeśli Twój projekt zostanie dostarczony co najmniej raz w tygodniu, tak jest. Jeśli Twój projekt nie jest elastyczny i jest dostarczany w odstępach sześciomiesięcznych, przeprowadź więcej regularnych recenzji.

Komentarze

  • Do ' jak zachęcić ', dodam, że wiele IDE pozwala na powiadamianie o braku dokumentacji jako ostrzeżenia. Alternatywnie, być może można przeprowadzić statyczną analizę dokumentacji w OSB (oczywiście samo to nie wystarczy).
  • @ SJuan76: Rzeczywiście. Program Visual Studio może nawet traktować brak komentarzy jako błąd w czasie kompilacji. Zredagowałem swoją odpowiedź, aby dodać notatkę na ten temat.
  • @ArseniMourzenko – przeczytałem, że możemy zachęcić do dokumentacji w Agile, dodając historie do dokumentacji. Ale nie powinny one blokować innych historii, tj. Definicji innych historii zakończonych, nie mogą obejmować uzupełniania historii z dokumentacji. Jak to brzmi?
  • @ArseniMourzenko – ' chciałbym dodać jeszcze dwa punkty do Twojej odpowiedzi. (1) W Jira itp. Cały czas dodawaj zadanie do dokumentacji. (2) Poproś o sprawdzenie jakichkolwiek dokumentów przez jeszcze 2 osoby &, aby potraktować to również jako zadanie. W ten sposób ludzie otrzymają przypomnienie, aby dokumentować &, aby uniknąć pisania dokumentów o niskiej jakości (z powodu recenzji). Jeśli nie ' nie nadasz mu priorytetu &, sprawdzisz go, wtedy stanie się zły. Wiem, że Amazon robi dużo dokumentów & recenzji dokumentów, może trochę za dużo.

Odpowiedź

Myślę, że należy dokonać rozróżnienia między komentarzami a dokumentacją. Chociaż komentarze są opisowe, nie są spójne, są rozproszone po całym kodzie. Komentarze nigdy nie powinny kompensować kodu, który nie jest wystarczająco samoopisujący, zamiast tego powinny wskazywać innym programistom na trudne części.

To, czy kod powinien zostać udokumentowany, zależy od skali projektu. Z pewnością są ludzie, którzy uważają, że wszystko powinno być udokumentowane i wydaje się, że łatwo jest to uzasadnić, bo kto odważyłby się sprzeciwić dokumentowanie wiedzy? Na szczęście tworzenie oprogramowania to nie nauka, a świat się nie zawali, jeśli szczegóły twojego małego programu staną się niejasne. Jeśli chodzi o profesjonalne oprogramowanie do użytku przez wielu programistów, tak, oczywiście, powinieneś udokumentować swój kod. Ale jeśli jesteś w pozycji do kodowania na tym poziomie, to oczywiście byś o tym wiedział.

tl; dr

Jeśli „prosisz, aby każdy projekt był dobrze udokumentowany,” wymagasz zbyt wiele .

Komentarze

  • Fortunately software development is not science Proszę powiedz mi więcej o tym, dlaczego w to wierzysz.
  • @Borat – Tworzenie oprogramowania jest dyscypliną inżynierską, co oznacza, że korzysta z narzędzi dostarczonych przez naukę.
  • Nie proszę, aby wszystko było udokumentowane. Powinno być wystarczy, aby dać ogólny przegląd tego, co robi system i kod. Np. Proszę mi powiedzieć, jak używać mojego telewizora. Nie ' nie obchodzi mnie, czy używa LCD, CRT, Rurki próżniowe lub urządzenia półprzewodnikowe do wykonania pracy . Jeśli osoba zajmująca się naprawami potrzebuje tych informacji, zrób dla niego osobną dokumentację.
  • Jeśli chcesz uzyskać ogólny przegląd, wystarczą nazwy identyfikatorów. Tak jak przycisk na telewizorze może mieć etykietę ” On „. Więc prosisz o szczegóły niskiego poziomu.
  • @LeopoldAsperger: Myślę, że Borat mówi o dokumentowaniu architektury i projektu, a nie metodach w klasach.

Dodaj komentarz

Twój adres email nie zostanie opublikowany. Pola, których wypełnienie jest wymagane, są oznaczone symbolem *