Czy istnieje logiczny powód automatycznego generowania dokumentacji kodu? [Zamknięte]

Automatyczne generowanie dokumentacji można wykonać za pomocą różnych narzędzi, a GhostDoc jest jednym z bardziej znanych. Jednak z definicji wszystko, co generuje, jest zbędne. Przegląda nazwy metod, klas itp. I wyświetla angielski, który mógłby wyjaśnić je bardziej dosłownie. W najlepszym przypadku robi to, co czytelnik mógłby zrobić w swojej głowie (przykłady zaczerpnięte stąd ):

/// <summary>
/// Initializes a new instance of the <see cref="Person"/> class.
/// </summary>
public Person() ...

W najgorszym przypadku może faktycznie wygenerować dziwaczną dokumentację, która faktycznie wprowadza w błąd, próbując heurystycznie zrozumieć znaczenie nazw:

/// <summary>
/// Riches the text selection changed.
/// </summary>
/// <param name="richTextBox">The rich text box.</param>
private void RichTextSelection_Changed(System.Windows.Controls.RichTextBox richTextBox) ...

Wydaje się, że podejście do GhostDoc brzmi: „wewnętrznie lepiej jest mieć jakąś formalną dokumentację XML”, ale kiedy ta dokumentacja jest w 100% zbędna, dlaczego? Czy to nie marnuje w najlepszym razie dużej ilości miejsca?

W moim miejscu pracy musimy dokumentować wszystko i prawie zawsze za pomocą automatycznie generowanych dokumentów GhostDoc. Czy to robisz i czy istnieją jakieś racjonalne powody, aby nie pozostawiać kodu bez dokumentacji, jeśli nie zamierzasz samodzielnie pisać dokumentacji?

[...] dokumentuje wszystko i prawie zawsze za pomocą automatycznie generowanych dokumentów GhostDoc. Czy to robisz i czy istnieją jakieś racjonalne powody, aby nie pozostawiać kodu bez dokumentacji, jeśli nie zamierzasz samodzielnie pisać dokumentacji?

Nie. Dokumentacja wygenerowana przez GhostDoc jest szablonem (podobny do tego, jak tworzenie nowej klasy OO w IDE tworzy płytkę grzewczą dla klasy z konstruktorem lub coś takiego). Przydatną częścią dokumentacji jest to, co nastąpi po dodaniu płyty grzewczej.

Podczas gdy trzeba dokumentować wszystko na swoim miejscu pracy, wydaje się swoimi coleagues znalazł idealny sposób wokół niego: po prostu udawać.

W języku o typie statycznym dokumentacja w stylu Javadoc nie jest przeznaczona dla autorów, lecz dla konsumentów. Autogeneracja po prostu ułatwia autorom prowadzenie dokumentacji, z której mogą korzystać inni ludzie.

Jeśli używasz statycznie wpisanego języka i nie piszesz biblioteki na użytek osób trzecich, autogeneracja nie kupuje dużo i według mojego doświadczenia jest rzadko używana. Jeśli używasz języka z dynamicznym pisaniem, dokumentacja w stylu javadoc jest często używana do dokumentowania typów, nawet tylko do użytku wewnętrznego, ale autogeneracja nie zna typów, więc oszczędzasz tylko ręcznego kopiowania płyty głównej.

Tak czy inaczej, nie myśl o autogeneracji jako o wytwarzaniu gotowego produktu. Pomyśl o tym jak o stworzeniu płyty kotłowej, więc wszelkie zmiany wprowadzane ręcznie są znaczące.

Czy istnieje logiczny powód automatycznego generowania dokumentacji kodu?

Z czyjej perspektywy?

Jeśli prowadziłem firmę lub grupę deweloperów, nie ma żadnego dobrego powodu. Jestem głęboko zaangażowany w obóz „komentarze powinny wyjaśniać dlaczego ”. Zmuszanie ludzi do komentowania klas / funkcji / właściwości jest gorsze niż bezwartościowe, ponieważ stają się przestarzałe, wprowadzają w błąd czytelnika, są wykorzystywane jako wymówka, aby nie tworzyć czytelnego kodu i tak dalej. Te komentarze marnują czas zarówno na ich pisanie, czytanie kodu, jak i spowodowane przez nie błędy. Niektórzy będą argumentować, że dokumenty API w stylu JavaDoc są powodem do komentowania, ale nawet pod tym argumentem niewielka część twojego kodu powinna być częścią publicznego API, a JavaDoc nie zastępuje rzeczywistych dokumentów API.

Jako programista pracowałem w kilku miejscach, które wymagają komentarzy w tych miejscach, pomimo mojej opinii. Ponieważ nie mam czasu ani cierpliwości, aby napisać bzdury, których nikt nie zamierza użyć, zamiast tego GhostDoc. To pozwala mi spędzać ten czas na robieniu rzeczy, które są ważne. Znacznie bardziej wydajne niż zmiana polityki korporacyjnej.

Kolejną dobrą rzeczą, którą znalazłem za pomocą GhostDoc, jest to, że służy on do sprawdzenia, czy moje imiona są dobre. Jeśli GhostDoc nie może wygenerować porządnej dokumentacji dla funkcji, to zapach, że nazwa mojej funkcji lub parametru może być kiepska. Chociaż nie będę używać narzędzia dla właśnie tego, że jest to miły efekt trochę z boku, jeśli mam być wykonane tracić czasu tak czy inaczej.

EDYCJA : Źle zrozumiałem pierwotne pytanie; chociaż myślę, że generowanie dokumentacji (tj. dokumentów niekodowanych ) może być niezwykle cenne (patrz oryginalna odpowiedź na temat Doxygen poniżej), automatyczne generowanie komentarzy (które jest tak naprawdę w GhostDoc) wydaje mi się szalone. Nie rozumiem, dlaczego ktokolwiek spodziewałby się, że program będzie w stanie odczytać niezakomentowany kod źródłowy i napisać komentarze, które naprawdę go wyjaśnią.

Jest dla mnie możliwe, że niezwykle „inteligentne” narzędzie do generowania komentarzy może być zaprogramowane do rozpoznawania pewnych wzorców i generowania komentarzy w stylu „jak”; na przykład może rozpoznać algorytm obliczania wariancji Knutha i podać komentarz wyjaśniający, jak on działa i dlaczego naiwny algorytm nie byłby odpowiedni. Być może takie narzędzie może nawet zostać zaprogramowane do rozpoznawania kanonicznych wzorców obiektowych (np. Abstract Factory) i wstawiania komentarzy wskazujących, który wzorzec jest używany i jakie klasy odgrywają role.

Ale moim zdaniem najbardziej przydatne komentarze nie wyjaśniają „jak” coś działa, ponieważ sam kod powinien to pokazywać, ale „ dlaczego ” komentuje, wyjaśniając „dlaczego” konkretna rzecz. Jak zauważył David Hammen w komentarzach poniżej, aby wygenerować komentarze „dlaczego”, narzędzie musiałoby „przeczytać umysł programisty”. Oczywiście jest to niemożliwe.

Na podstawie podanych przykładów wydaje się jednak, że GhostDoc nawet nie wykonuje zadania tworzenia prawdziwych komentarzy w stylu „jak”. Moim zdaniem jest więc gorsze niż bezużyteczne, ponieważ to, co generuje, może być głupie i mylące (jak w drugim przykładzie).

Oryginalna odpowiedź: dlaczego automatyczne wyodrębnianie i formatowanie dokumentacji jest dobrym pomysłem

Mój zespół programistów używa Doxygen. Głównym tego powodem jest to, że potrzebujemy dokumentacji kodu innego niż kod źródłowy (tj. Czytelnej dla nieprogramiści) dokumentacji funkcji / zachowania / itp. Kodu, ale uważamy, że lepszym rozwiązaniem jest zintegrowanie tego z samym kodem źródłowym niż zachowaj jako drugi dokument . Pomaga nam to zsynchronizować dokumentację z kodem źródłowym (choć oczywiście tego nigdy nie da się w pełni zapewnić, a tym bardziej nie zautomatyzować) i minimalizuje koszty pisania dokumentacji (ponieważ dokumentację fragmentu kodu można w prosty sposób włączyć do plik zawierający sam kod).

Dlatego naszym celem Doxygen nie jest wyodrębnianie informacji z samego kodu, ale utrzymywanie dokumentacji kodu źródłowego jak najbliżej samego kodu źródłowego.

To pozwala nam również użyć jednego narzędzia do stworzenia zarówno „teorii operacji”, która opisuje całą naszą bazę kodu, jak i kilku zestawów „informacji o wersji”, które opisują produkt, ale w rzeczywistości nie zawierają żadnej „dokumentacji kodu” w typowy sens.

Jeśli chodzi o to, dlaczego potrzebujemy dokumentacji kodu źródłowego dotyczącej zachowania naszego kodu, istnieją dwa powody:

• Nasz produkt to nie tylko oprogramowanie; jest to złożone narzędzie, które integruje wiele komponentów sprzętowych, w tym niektóre fantazyjne lasery i fluidy. Potrzebujemy inżynierów bez dużego doświadczenia w oprogramowaniu, aby dobrze rozumieli dokładnie, jak zachowują się wewnętrzne elementy naszego kodu, a powiedzenie im, że „czytają kod źródłowy”, nie osiągnie tego.
• Musimy przestrzegać kilku przepisów dotyczących jakości, z których niektóre są wewnętrznie upoważnione przez firmę, a inne prawnie upoważnione przez rząd federalny. Chociaż proces jakości jest (lub przynajmniej może być) niezwykle cenny i pomocny, wiąże się z nie mniej istotnym nakładem pracy, którego częścią jest obowiązek zespołu oprogramowania do dostarczenia tego rodzaju szczegółowej dokumentacji oprogramowania. Ponownie zintegrowanie tej dokumentacji z samym kodem minimalizuje koszty ogólne i pomaga nam aktualizować dokumentację.

Zwróć uwagę, że drugi punkt jest dość podobny do tego, który podał kilka innych odpowiedzi na temat tego, że menedżerowie chcą mieć pewność (/ chwalenie się prawami), że istnieje pewna dokumentacja (niezależnie od jakości) dla każdego kodu źródłowego; ten sposób jego sformułowania nie uwzględnia jednak faktu, że dokumentacja zlecona zewnętrznie może w rzeczywistości mieć pewne uzasadnione zalety.

Z pewnością zautomatyzowana dokumentacja jest szczególnie pomocna, gdy może odtworzyć wnikliwe, odpowiednie opisy napisane przez autorów kodu. W przeciwnym razie jest to po prostu uwielbiony automatyczny formatator.

Ale formatowanie nie jest bezużyteczne. Warto znaleźć publiczne metody dużego elementu na jednym spojrzeniu, posortowane i gwarantowane, że są kompletne. Jeśli potrzebujesz frobnickmutatora, a go nie ma, wiesz, że nie ma go bez brodzenia przez kod źródłowy. (Negatywne wyniki mają również wartość: wiesz, że musisz coś zrobić i masz na to więcej czasu, ponieważ nie musiałeś brodzić).

Tak, automatyczne generowanie dokumentów dodaje pewnej wartości. Z pewnością nie tak bardzo, jak przypuszczają menedżerowie, i zwykle nie tak bardzo, jak naprawdę dobry edytor kopii, ale nic.

W tej formie jest to gorsze niż bezużyteczne, ale tylko dlatego, że opiera się wyłącznie na podpisie publicznym (który, w przypadku Javadoc, jest widoczny dla każdego, kto czyta dokument API).

Możliwe jest jednak pisanie automatycznych narzędzi do dokumentacji, które uwzględniają również treść metody. Jako dowód koncepcji napisałem kiepską małą wtyczkę Eclipse, która dodaje Javadocowi listę innych metod wywoływanych z udokumentowanej metody. (Oczywiście nie każde wywołanie można zdefiniować filtry, na przykład według pakietu).

I faktycznie okazało się, że jest to całkiem przydatne, gdy mapuję mentalnie zupełnie nieznaną bazę kodu. To prawda, że ​​jest to bardzo ograniczony przypadek użycia, ale zdecydowanie był pomocny.

Na podstawie tego doświadczenia odpowiedź na pytanie brzmi: tak, ale potrzebujemy znacznie inteligentniejszych narzędzi.

Aktualizacja: Oczywiście dodatkowym pytaniem (które należy zadać przed napisaniem jakiejkolwiek dokumentacji) jest to, kim jest grupa docelowa. Jeśli dokumentujemy publiczny interfejs API dla klientów tego interfejsu API, dodanie wszystkich tych szczegółów implementacji jest dużym nie-nie, ponieważ wszystko, co umieścisz w Javadoc, jest technicznie częścią API.

Ale jeśli docelowymi odbiorcami są inni programiści pracujący nad tym samym produktem, automatyczne dodawanie informacji o szczegółach implementacji, takich jak metody modyfikujące lub odczytujące określone pole, jest zarówno dopuszczalne, jak i użyteczne.

Nie wiem o innych środowiskach, ale jeśli chodzi o duże (często otwarte) projekty PHP napisane przez innych ludzi, phpXRef jest absolutnym narzędziem ratującym życie (szczególnie jeśli dokument jest umieszczony online i Google może go zindeksować).

Nawet źle skomentowany projekt może przynajmniej pomóc mi wyśledzić, gdzie rzeczy zostały zdefiniowane i gdzie są używane (na przykład podczas refaktoryzacji).

Dobrze skomentowane, powstałe strony tworzą idealną Biblię do bazy kodu (w każdym razie do moich zastosowań).

Co więcej, moje preferowane IDE automatycznie wygeneruje blok komentarzy (jeśli wpisuję / **), co dla mnie działa w przybliżeniu w 75%. To zdumiewające, jak wiele głupich rzeczy przestałem popełniać przez całe życie mojego programisty tylko dlatego, że musiałem wyjaśniać innym ludziom (i przyszłości mnie), co robię. Kiedy mój komentarz do generatora dokumentów jest większy niż metoda, zwykle oznacza to, że nie wypiłem wystarczającej ilości kawy i być może zechcę myśleć trochę bardziej.

Te same bloki komentarzy tworzą również tekst „pomocy” uzupełniania, aby zobaczyć dokładnie to, czego oczekiwano (przez innych programistów) podczas pisania wywołania funkcji. Jest to dla mnie ogromny wzrost wydajności (szczególnie w tych rzadkich przypadkach, w których inny pomocny programista napisał „na miłość boską, nie rób / nie rób X” - co może zaoszczędzić wiele bólu.

Nie mogę wystarczająco podkreślić, jak przydatne jest określenie oczekiwanych typów danych wejściowych w złożonych (i często źle nazwanych) projektach PHP oraz kolejności argumentów w rzadziej używanych metodach. Nawet z własnym kodem nie zawsze pamiętam, jakie argumenty podałem za czymś, czego nie dotknąłem od wieków.

W jednym przypadku oznaczało to, że źródłem powtarzających się problemów było to, że z jakiegoś powodu, który źle odbija się na poprzednich programistach, niektóre funkcje, a nawet stałe zostały zdefiniowane w ogromnej liczbie miejsc (z pewnym stopniem niespójności dla dodatkowej „zabawy”) . To był znak, by odejść od projektu.

W większych projektach, które rozpoczęły się, zanim dołączyłem, widzę, który programista (zakładając, że oznaczył plik klasy nazwą i adresem e-mail) utworzył klasę, a po prostu możliwość znalezienia odpowiedniego programu i rozmowy z nim jest niezwykle pomocna.

Automatyczne listy zadań - użycie tagu @todo (powszechnego w projektach, w których pracuję) oznacza, że ​​dokumentacja może śledzić rzeczy, które wymagają więcej pracy (lub funkcji, o których wiadomo, że ich brakuje). Ponownie moje IDE śledzi to i to samo służy jako dobry przewodnik, co najpierw wymaga mojej uwagi.

Wreszcie (i to dla mnie bardzo ważne) eliminuje to trywialny narzut związany z pisaniem tego wszystkiego, a następnie próbą aktualizowania go, gdy niektórzy (czytający wielu) koderzy dokonują zmian i nie rozmawiają z opiekunami dokumentacji.

Przyczyny obejmują:

• Oszczędzając później programistom stos czasu,
• Śledzenie, gdzie funkcje są wywoływane (i definiowane),
• Wykrywanie głupiego kodowania,
• Znajdowanie (jak zauważył inny), gdy czegoś oczywiście brakuje,
• Uproszczenie refaktoryzacji (nigdy dużo zabawy)
• (W wielu przypadkach) uzyskanie pomysłu na to, co programista próbował zrobić (zakładając, że zostawił kilka notatek).
• Jeśli projekt jest na tyle skomplikowany, że działa wiele licencji (bez zabawy), mogę szybko sprawdzić, które licencje dotyczą danej sekcji. Trzeba przyznać, że jest to bonus dodatkowy.
• Dowiedz się, z kim porozmawiać o pliku projektu.
• Automatyczne listy zadań

Nie lekceważ też wartości, jaką daje zadowolenie spiczastych włosów szefów za naciśnięciem jednego przycisku.

W skrócie, „automatyczne komentarze do dokumentacji” są niezbędne dla moich nawyków kodowania. Jestem pewien, że wielu uważa, że ​​to kiepskie, ale jestem również pewien, że jest całkiem sporo ludzi, którzy dokładnie wiedzą, co mówię. Nie wiem, jak przetrwałem, zanim odkryłem phpXRef (i moje ulubione IDE).

Często dobrze jest używać generatorów dokumentacji do tworzenia komentarzy typu „płyta główna” lub komentarzy „stand-in”, które są następnie zmieniane przez rzeczywistych programistów. Często używam funkcji auto-JavaDoc Eclipse do generowania komentarza nagłówka z typami parametrów i zwracanymi wartościami, które są już wypełnione, a następnie po prostu dodaj „mięso” dokumentacji.

Jako programista C # używam Stylecop, który nakazuje komentarze dla wszystkich klas, metod itp. Generuję te komentarze za pomocą narzędzia. Przez większość czasu komentarze generowane przez narzędzie są wystarczające i można je wywnioskować na podstawie nazwy obiektu, np. Klasa Person ma pole ID.

Ale JEŻELI chcę skomentować nieoczywistą metodę, bardzo łatwo jest rozszerzyć dokumentację płyty kotłowej i kilka wyjaśnień na temat jej działania. Jako przykład: mam metodę w mojej klasie Person, która zwraca FirstName + Lastname, ale dodałem trochę docu o tym, co się dzieje, gdy brakuje jednego z nich.

Krótko mówiąc: myślę, że dokument docu może być szkodliwy, jeśli nigdy nie zmienisz tekstu dostarczonego przez generator. W takim przypadku jest to po prostu szum linii. Ale jeśli widzisz je jako szablon, obniżają pasek, aby zapewnić dobre i użyteczne komentarze dla ciebie lub twoich konsumentów. Czy możesz napisać komentarze bez ich automatycznego generowania? Jasne, ale musisz przestrzegać formatu (który w przypadku C # jest dość gadatliwy i irytujący, aby wygenerować ręcznie), a to zmniejsza szansę, że naprawdę podasz ten komentarz na al.

Unikaj tautologii

Jedynym czasem, gdy potrzebujesz jakiejkolwiek dokumentacji do kodu jest wyjaśnienie, dlaczego metoda / funkcja coś robi, nazwa powinna wystarczyć do tego , co robi.

Jeśli robisz coś, co nie jest idiomatyczne lub narusza zasadę najmniejszego zdziwienia, wymagana jest dokumentacja.

Automatycznie generowana dokumentacja, która jest tylko formatyzatorem do generowania informacji, jest prawie wymagana przez konsumentów twojego kodu. Javadoc robi to wyjątkowo dobrze.

Nie wszystkie rzeczy powinny być dokumentowane ręcznie

Rzeczy takie jak metody getXXX / setXXX powinny być zrozumiałe, więc dokumentacja automatycznego generowania, która tylko informuje, że istnieje, zostanie dobrze przyjęta.

Dokumentacja kodu, przynajmniej „automatyczna”, stanowi najmniej powszechny mianownik dla osób próbujących zrozumieć aplikację.

Najbardziej zaawansowani użytkownicy nie docenią automatycznej dokumentacji kodu. Woleliby raczej „ukierunkowaną” dokumentację, która mówi im, co (niewiele) trzeba powiedzieć.

Najmniej zaawansowani użytkownicy nie doceniliby tego z przeciwnego powodu; i tak by tego nie zrozumieli.

Najbardziej „doceniającymi” użytkownikami automatycznej dokumentacji kodu są ci, dla których „odrobina wiedzy” jest niebezpieczną rzeczą. „Mogą oni rozumieć dokumentację (choć prawdopodobnie ją rozumieją), ale mogą się dobrze czuć w ciągłej pętli. „Ta grupa odbiorców obejmuje większość typów„ menedżerskich ”. Jeśli to twoi główni odbiorcy, automatyczna dokumentacja kodu może być dobrą rzeczą.

na proste pytanie „dlaczego generować dokumenty” można po prostu odpowiedzieć, pokazując MSDN.

Wyobraź sobie, że próbujesz napisać program korzystający z dowolnej biblioteki, w której nie ma dokumentacji API. To byłby koszmar. MSDN jest doskonałym przykładem tego rodzaju dokumentów, które można wygenerować z kodu źródłowego i komentarzy i stanowią istotne źródło dla programistów.

Jeśli piszesz aplikację (tj. Nie bibliotekę, która ma być używana przez innych), być może jest powód, aby nie przejmować się - ale nawet wtedy, jak duża, tylko do użytku wewnętrznego, aplikacja nie zawiera wielu bibliotek tak czy siak? Gdy dołączysz do takiego zespołu, pomocny będzie dokument API do przeglądania.

Żadne narzędzie nie napisze dla ciebie dokumentacji, ale dają ci szablon, który i tak musiałbyś napisać ręcznie, niektóre narzędzia (np. Doxygen) również generują diagramy i listy referencyjne (na przykład funkcje wywoływane i wywołujące) ), którego nie można łatwo wykryć, nawet patrząc na kod źródłowy.

Oczywiście pragmatyczny zdrowy rozsądek należy stosować do tego, co zostaje udokumentowane, właściwości i drobne funkcje można zignorować (i pominąć generowanie nawet w narzędziach), ale w żadnym momencie nikt nie powinien mówić „jest kod źródłowy, to wystarczająca dokumentacja” w dowolnym momencie .