Ile dokumentacji wystarczy?

Ile dokumentacji technicznej (dla przyszłych programistów) wystarcza ? Czy istnieje odpowiedni stosunek między kodowaniem godzin a dokumentowaniem godzin, który jest odpowiedni?

Papadimoulis twierdzi , że powinieneś

stworzyć najmniejszą ilość dokumentacji potrzebnej do jak najlepszego zrozumienia,

Czy to dobra wskazówka, czy są jakieś konkretne rzeczy, które powinienem stworzyć?

Co powiesz na jakieś testy użyteczności korytarza? Pokaż kod i dokumentację programistom, którzy nie znają projektu. Jeśli możesz to zrobić bez przytłaczającej potrzeby wyjaśnienia czegoś podczas oglądania kodu, masz dość.

La perfection est atteinte non pas quand il n'y a plus rien à ajouter, mais quand il n'y a plus rien à emerytura.
Antoine de Saint-Exupéry

Od jakiegoś czasu zastanawiam się nad tym tematem.

Mój wniosek jest taki - nie jest to kwestia ilości, ale jakości i kontekstu.

Na przykład odpowiednia struktura projektu pokonuje komentarze wyjaśniające lokalizację plików (implementacja a zamiar)

Podobnie, klasyfikacja w celu wyjaśnienia nazewnictwa pokonuje kontekst (Id na pacjencie -> Patient.Id).

Wierzę, że DDD ma coś do powiedzenia w dobrej dokumentacji - klasyfikacja zapewnia kontekst, kontekst tworzy granice, a granice prowadzą do zamierzonych implementacji (to jest to, gdzie należy, a nie musi istnieć).

Sam kod nie jest wystarczająco dobry, aby uznać go za dokumentację. Problem w większości przypadków nie polega na tym, że działanie kodów jest komentowane lub nie komentowane, ale raczej siła napędowa (logika domeny) nie jest.

Czasami zapominamy, kto jest szefem - jeśli kod się zmieni, logika domeny lub rozumowanie nie powinny, ale jeśli logika domeny lub rozumowanie zmieni się, kod na pewno się zmieni.

Spójność jest również bardzo ważna - sama konwencja jest bezużyteczna, jeśli nie jest spójna.

Wzorce projektowe to nie tylko „dobra praktyka” - to żargon, który programiści powinni zrozumieć. Mówienie deweloperowi, aby dodał nowy typ do fabryki, jest lepiej zrozumiałe niż dodawanie nowego typu do metody (gdzie kontekst i spójność są słabe lub brakuje).

Połowa walki to znajomość .

Na marginesie, interfejsy API, które wydają się faworyzować wiele dokumentacji, są również bardzo wrażliwe na domeny i kontekst. Czasami funkcja kopiowania nie jest zła (to samo, różne konteksty) i powinna być traktowana jako osobna.

Jeśli chodzi o komentowanie, zawsze warto wskazać logikę domeny leżącą u podstaw tego rozumowania.

Na przykład pracujesz w branży medycznej. W swojej metodzie piszesz „IsPatientSecure = true;”

Teraz każdy porządny programista może dowiedzieć się, że pacjent jest oznaczony jako bezpieczny. Ale dlaczego? Jakie są implikacje?

W tym przypadku pacjent jest więźniem, który został bezpiecznie przeniesiony do szpitala poza siedzibą. Wiedząc o tym, łatwiej jest wyobrazić sobie wydarzenia, które doprowadziły do ​​tego momentu (i być może to, co wciąż musi się wydarzyć).

Może ten post wydaje się w najlepszym razie filozoficzny - ale pamiętaj, że piszesz o „rozumowaniu” lub „logice”, a nie o kodzie.

Zgadzam się z cytatem Papadimouslis. Kod źródłowy może mówić sam za siebie, ale kod nie może powiedzieć, dlaczego istnieje, jak należy go używać i jak powinien on zachowywać się.

Nie znam dobrego stosunku.

Odziedziczyłem setki linii kodu z bardzo małą dokumentacją. Trudno mi zrozumieć, dlaczego kod został napisany. Po tym, jak dowiedziałem się, dlaczego kod został napisany, musiałem wymyślić, jak go użyć. Po tym, jak się o tym dowiedziałem, musiałem zrozumieć, jak powinno się zachowywać, aby móc obsługiwać i utrzymywać kod.

Tylko z doświadczenia nie rób zbyt szczegółowych komentarzy, w przeciwnym razie będziesz musiał zachować właściwy kod ORAZ dokumentację. Koszmar, gdy dokumentacja i kod nie są zsynchronizowane.

Wystarczająco, abyś przestał się zastanawiać.

Jeśli w którymkolwiek momencie swojej pracy masz ochotę „hmm, może powinienem to udokumentować”, zrób to. Następnie, jeśli napisałeś jakąś dokumentację i jesteś w stylu „może powinienem to wyjaśnić więcej”, zrób to.

Powtarzaj płukanie, aż to uczucie zniknie.

Przekonałem się, że podejście oparte na ryzyku, takie jak przedstawione w książce George'a Fairbanksa „ Just Enough Software Architecture” działa bardzo dobrze, aby zrozumieć, ile dokumentacji wystarczy. Możesz przeczytać sekcję prezentującą tę koncepcję (rozdział 3) na jego stronie internetowej, ale główną ideą jest:

• Wyrażaj rzeczy, które martwią cię „zrozumieniem systemu” jako ryzyko
• Priorytetyzuj ryzyko
• Ograniczaj ryzyko, dopóki Twój zespół nie poczuje, że ryzyko projektu zostało wystarczająco zmniejszone. W takim przypadku prawdopodobnie będziesz tworzyć dokumentację.

Aby pomóc w skalibrowaniu obaw i uszeregowaniu pod względem ważności ryzyka, uznałem za pomocne określenie kilku celów zwanych progiem sukcesu , czyli minimalnego zestawu celów, które zespół uważa za „udany” projekt. Z punktu widzenia dokumentacji przykładowym ToS może być coś w rodzaju: „Deweloper powinien być w stanie zbudować prostą wtyczkę w ciągu 4 godzin od pierwszego uruchomienia frameworka”.

Teraz zidentyfikuj niektóre zagrożenia. Z systemem, który zbudowałeś (lub budujesz), jakie rzeczy najbardziej martwią Twój zespół? Wyrażaj je jako oświadczenia o ryzyku. Podoba mi się styl SEI-warunek-konsekwencja, ale są też inne. Przykłady:

• Model danych jest duży i złożony; programiści mogą nie wiedzieć, których elementów danych użyć w danej sytuacji.
• System ma ograniczenia połączeń API w celu zwiększenia niezawodności; programiści mogą przypadkowo przekroczyć limit połączeń.
• Wtyczki są wykorzystywane w kilku kolejnych krokach; programiści mogą nie tworzyć wtyczek, mając na uwadze te uporządkowane kroki.

Teraz, jako zespół, nadaj priorytet ryzykom. Głosowanie wielokrotne działa wyjątkowo dobrze.

Ogranicz ryzyko o najwyższym priorytecie i powtórz od identyfikacji, dopóki ryzyko niepowodzenia projektu (zdefiniowane przez próg sukcesu) nie przekroczy dopuszczalnego limitu. Ogólnie oznacza to, że masz pewne ryzyko, które zespół zgodzi się, nie stanowi większego problemu. Pamiętaj, że prawdopodobnie nie będziesz chciał zminimalizować wszystkich zagrożeń. Przykładową strategią ograniczania ryzyka dla ostatniego powyższego ryzyka może być utworzenie samouczka.

Jak najmniej, ale tyle, ile jest konieczne

Nie pamiętam, gdzie i kiedy pierwszy raz to usłyszałem, ale jest to maksyma w wielu aplikacjach.

Im bardziej złożona technologia lub aplikacja, tym więcej dokumentacji będzie potrzebne (oczywiście), ale najwyraźniej nie chcesz tracić czasu na przesadzanie.

„Test korytarza” JohnFxa jest zdrowy. Ale zaufaj sobie; opracowałeś kod, a więc ty ze wszystkich ludzi powinieneś wyczuć elementy wymagające szczególnej uwagi oraz elementy, które będą oczywiste dla wszystkich. Pomyśl o zmaganiach, jakie miałeś przy tworzeniu kodu, a prawdopodobnie będziesz miał pomysł, co zobaczy inny programista, gdy spojrzy na Twój kod.

Zapomnij o jakimkolwiek związku między wysiłkiem włożonym w kodowanie a wysiłkiem włożonym w dokumentację.

Uważam, że nie można tego dokładnie określić. Dokumentowanie ma na celu dostarczenie wiedzy, która nie jest łatwa do zebrania z surowego kodu w formie, aby inni mogli zrozumieć, a może nawet utrzymać ten surowy kod.

Dlatego jedynym sposobem na sprawdzenie, czy masz wystarczającą dokumentację, jest zapytanie grupy docelowej, czy jest wystarczająco dobra. Uważam, że proces „wzajemnej oceny” jest bardzo dobry w przeprowadzaniu tego z góry. Zauważ, ile trzeba wyjaśnienia, aby twój rówieśnik zrozumiał, o czym mówisz, i staraj się to zminimalizować.

Jeśli nigdy wcześniej tego nie robiłeś, nie możesz oszacować, ile pracy to zajmie, ale po kilku iteracjach uzyskasz znacznie lepsze pojęcie o tym, ile potrzeba.