Badania zysków / strat wydajności dokumentacji

Po wielu poszukiwaniach nie udało mi się odpowiedzieć na podstawowe pytanie dotyczące założonego znanego w świecie twórców oprogramowania:

CO JEST ZNANE:

Egzekwowanie ścisłej polityki dotyczącej odpowiedniej dokumentacji kodu (czy to znaczników Doxygen, Javadoc, czy po prostu mnóstwa komentarzy) wydłuża czas potrzebny na opracowanie kodu.

ALE:

Posiadanie dokładnej dokumentacji (lub nawet interfejsu API) niesie ze sobą wzrost wydajności (jak się zakłada) nowych i doświadczonych programistów, którzy dodają funkcje lub naprawiają błędy.

PYTANIE:

Czy dodatkowy czas potrzebny na opracowanie dokumentacji jest równoważony wzrostem wydajności na dalszych etapach (w sensie ściśle ekonomicznym)?

Szukam studiów przypadków lub odpowiedzi, które mogą przynieść obiektywne dowody potwierdzające wyciągnięte wnioski.

Z góry dziękuję!

Artykuł „Styl typograficzny jest więcej niż kosmetyczny” jest raczej stary, ale bardzo interesujący: http://portal.acm.org/citation.cfm?id=78611 .

Ponieważ jest stary, nie zawiera wszystkich wymyślnych rzeczy, które byłyby możliwe w dzisiejszych czasach, ale wyraźnie pokazuje, że dokumentacja kodu ma znaczenie.

Dla tych, którzy podobnie jak ja nie mają dostępu do biblioteki cyfrowej ACM, stworzyli dwie grupy programistów i dali im ten sam kod do nauki. Grupa A otrzymała tylko kod ze zwykłymi komentarzami, grupa B otrzymała dość wydrukowaną listę ze spisem treści, odsyłaczami i wszystkimi subtelnościami, które były możliwe w 1990 roku.

Następnie poprosili dwie grupy o wykonanie pewnych zadań na kodzie (np. Rozszerzenie funkcji, znalezienie błędu, ...) i ocenili je pod względem szybkości i jakości odpowiedzi.

Aby zrównoważyć grupę, mieli taką samą liczbę ekspertów i młodszych programistów.

Cóż, okazało się, że grupa B (ta z dość wydrukowanym zestawieniem) uzyskała lepszy wynik niż grupa A w licznych testach. A w konkretnych przypadkach tylko najbardziej ekspertom z grupy A udało się prześcignąć młodszego programistę z grupy B.

Artykuł mówi więcej, ale o tym pamiętam (wciąż powinienem gdzieś wydrukować artykuł).

Dla mnie przynajmniej wydaje się oczywiste, że czytelny kod jest wart dużo więcej niż dokumentacja, która służy tylko do zrekompensowania źle napisanego kodu. Zwykle traktuję komentarze w kodzie jako wyzwanie, aby sprawdzić, czy mogę usunąć komentarz, przepisując kod i sprawiając, że będzie on bardziej zrozumiały.

Nie mogę tego poprzeć żadnym twardym dowodem, poza zdrowym rozsądkiem.

Nie mam żadnych badań do cytowania, ale mam prostą zasadę: jeśli wrócę do mojego kodu dwa tygodnie później i nie mogę od razu dowiedzieć się, co zrobiłem, albo potrzebuje więcej komentarzy, albo musi zostać uproszczony .

Oczywiście sposób działania kodu powinien być udokumentowany przez sam kod. Ale czas spędzony na pisaniu komentarzy, które dokładnie i zwięźle wyjaśniają, dlaczego kod jest napisany w taki sposób, że prawie na pewno zwraca się na dłuższą metę, nawet jeśli jesteś jedyną osobą, która utrzymuje kod.

Żywotność oprogramowania zostanie poświęcona głównie na etapie konserwacji, więc wszystko, co pomoże programiście, który przyjdzie za tobą, zrozumieć, co się dzieje, prawie na pewno zapewni zwroty finansowe, ponieważ pomaga programistom przyspieszyć.

W przypadku dowolnego interfejsu API, który jest nieco niebanalny, dokumentowanie interfejsu API w kodzie jest prawie bezużyteczne. Wynika to z faktu, że moc interfejsu API wynika z tego, jak działa on razem jako całość (a nie jak działają poszczególne metody / obiekty).

Dlatego bardziej pomocna niż prawdziwa dokumentacja jest dokument podobny do książki kucharskiej, który wyjaśnia oczekiwane wzorce użytkowania interfejsu API i przykłady sposobów rozwiązania niektórych oczywistych sytuacji (wykorzystujących większość (nie 100%) interfejsu API).

Decyzja, czy dana metoda jest bez narzędzi, które prawdopodobnie nie zostały jeszcze wynalezione, jest zbyt subiektywna, aby wymagać napisania dokumentacji.

Wszelkie najlepsze domysły, takie jak „wszystkie metody publiczne” lub wszystkie klasy w danym pakiecie itp., Mogą pomóc, ale są zbyt surowe, aby zalecać je poza konkretnymi przypadkami użycia.

Moja sugestia: Naucz deweloperów dobrych praktyk, jak identyfikować metody, które są ważne do udokumentowania (formalne lub nieformalne API, powszechnie używane, metody pośredniczące, złożone lub ezoteryczne) i pozwól im rządzić sobą.

(Ściśle powiązane: Czy może być zbyt duża jednolitość standardów kodowania? )

^{Przepraszam, że nie mam żadnych badań, ale podejrzewam, że jest to problem, w którym wszelkie próby zmierzenia go zbyt mocno wpłynęłyby na wynik, aby wyciągnąć ogólne wnioski.}

Myślę, że w tym względzie musimy oddzielić „zwykły” kod od publicznych interfejsów API . Jeśli chodzi o zwykły kod, zdecydowanie zgodziłem się z większością innych osób odpowiadających w tym kodzie, że kod ten powinien być samodokumentujący i czytać prawie jak proza . Jeśli mój kod nie jest taki, to zwykle jest to moja wina, więc zamiast dokumentować, należy go ponownie opracować. Małe metody, które robią tylko jedną rzecz na raz, pracując na jednym poziomie abstrakcji, o poprawnej i opisowej nazwie , mogą pójść w świetny sposób do osiągnięcia tego.

Problem z komentarzami polega na tym, że gniją. Jak tylko dodasz komentarz, zacznie on żyć niezależnie od kodu, który mu towarzyszy. Jak duża jest szansa, że ​​następny programista, który zmodyfikuje kod, również odpowiednio zaktualizuje powiązane komentarze? Z mojego doświadczenia wynika, że ​​blisko zera. Efektem końcowym po kilku modyfikacjach jest to, że komentarz intryguje lub wprowadza w błąd ludzi zamiast im pomagać.

Możliwe wyjątki to kod zoptymalizowany pod kątem wydajności lub użycie określonego algorytmu . W takim przypadku przydatne jest dodanie komentarzy opisujących, jak wygląda kod, odniesienie do algorytmu itp.

Najważniejsze prace na ten temat to Clean Code .

OTOH publiczny interfejs API również powinien być dobrze udokumentowany w Javadoc . Ponieważ może być używany przez niezliczoną liczbę nieznajomych z niezwykle różnorodnymi umiejętnościami i założeniami, należy podjąć wszelkie środki ostrożności, aby korzystanie z niego było tak proste i jednoznaczne, jak to możliwe. Jest to nadal w dużej mierze kwestia właściwego zaprojektowania interfejsu API, ale dokumentacja również odgrywa ważną rolę.

Problemem jest to, czy oszczędzasz czas, dokumentując swój kod, a nie każdy kolejny programista musi próbować dowiedzieć się, co robi. Jeśli Twój kod przechodzi przez przegląd kodu, a nikt nie wywołuje żadnych pytań na temat jego działania, prawdopodobnie jesteś w dobrej formie. Nietrudno jest opisać założenia dotyczące danych wejściowych. Powiedzmy, że twoja metoda pobiera obiekt liczby całkowitej i zwraca obiekt ciągu. Czy int może być zerowy? Czy istnieje wartość min / max (oprócz liczby całkowitej.MinValue / MaxValue)? Czy może zwrócić pusty ciąg lub zero? Czy to rzuca jakieś wyjątki? Oczywiście każdy może je znaleźć przez inspekcję, ale jeśli wystarczająca liczba innych deweloperów będzie używać twojego kodu, zaoszczędzenie kilku minut jest warte twojego czasu. Ponadto daje testerom wsparcie w tworzeniu testów w celu potwierdzenia kodu.

Jest to z pewnością interesujący temat, ponieważ zawsze istniały argumenty, czy programista powinien spędzać czas na tworzeniu lub utrzymywaniu dokumentów, czy nie, ale faktem jest, że kod powinien być dobrze napisany i bardzo dobrze skomentowany, w ten sposób, gdy programista ponownie odwiedza kod, niż on lub ona nie musi tracić czasu na zastanawianie się nad tym, jak napisano kod i co miałoby zrobić przede wszystkim, jeśli nowy członek zespołu dołączy do zespołu, niż może zrozumieć funkcjonalność i działanie kodu, ponieważ został on wyraźnie udokumentowany.

Tak więc kod powinien być bardzo dobrze skomentowany, podobnie jak kod samodokumentujący, który nie wymaga żadnej zewnętrznej dokumentacji.

W swojej karierze widziałem kod o różnym poziomie dokumentacji i jakości (zauważ, że dokumentacja i jakość są kwestiami ortoganalnymi). Wolę czas poświęcony na dokumentację niż na poprawę jakości. W prostym przypadku istnieją narzędzia, takie jak GhostDoc, które mogą przeglądać funkcje i generować komentarze do dokumentów. Jeśli GhostDoc może wygenerować znaczący komentarz, który mówi, co robi twoja funkcja, to oczywiście osiągnąłeś cel posiadania dobrze nazwanych funkcji.

W wielu przypadkach GhostDoc nie może nawet zacząć mówić ci, co tak naprawdę robi funkcja. Lepiej poświęć swój czas na rozwiązanie tego problemu i (być może) użycie ghostdoc do automatycznego wygenerowania kodu.

Zobacz Clean Code i PPP autorstwa Boba Martina, aby uzyskać głębszą dyskusję.