Dokumentacja kodu: publiczny czy niepubliczny?

Jestem jednym z tych programistów, którzy myślą, że napisany kod powinien być zrozumiały i czytać jak książkę.

JEDNAK, opracowując kod biblioteki dla innych osób, staram się umieszczać jak najwięcej dokumentacji w plikach nagłówków; co rodzi pytanie: czy warto udokumentować metody niepubliczne? Nie będą ich używać bezpośrednio, w rzeczywistości nie mogą. Jednocześnie, jeśli rozprowadzę surowy kod (choć niechętnie), te niepubliczne metody będą widoczne i mogą wymagać wyjaśnienia.

Po prostu szukam standardów i praktyk, które wszyscy widzicie lub używacie podczas swoich podróży.

Nigdy nie rozważałbym pominięcia dokumentacji dotyczącej elementów wewnętrznych tylko dlatego, że „użytkownik końcowy” ich nie użyje; utrzymanie kodu to więcej niż wystarczający powód, aby dołączyć komentarze do dokumentacji dla wszystkich komponentów, w szczególności dla elementów wewnętrznych, które wydają się być najbardziej złożoną (i często zmieniającą się) częścią.

To powiedziawszy, może istnieć uzasadniony argument, aby ograniczyć je do kodu źródłowego innego niż nagłówek (a nie publicznie udokumentowane), w celu zachowania abstrakcji.

To wszystko jest raczej subiektywne.

Ok, dodam też swój sposób komentowania / dokumentowania do obrazu dla urozmaicenia. Uzasadnieniem jest to, że unikam opisywania funkcji lub funkcji składowych zadeklarowanych tam tylko w nagłówku. Z jednej strony obawiam się, że dodam zbyt dużo hałasu do nagłówka. Z drugiej strony dokumentacja wraz z definicją jest łatwiejsza dla opiekuna. Doxygen nie przejmuje się w żaden sposób i może odfiltrować szeregowców w razie potrzeby.

W nagłówku klasy:

• dołączone nagłówki (dlaczego)
• definicje klas zawsze (cel i obowiązki)
• funkcje czysto wirtualne zawsze (pełna umowa)
• funkcje wbudowane, chyba że są zrozumiałe dla użytkownika
• inne zadeklarowane typy, chyba że oczywiste
• członkowie danych statycznych (dlaczego)
• inni członkowie danych, chyba że są to oczywiste
• makra, jeśli istnieją (umowa i dlaczego)

W kodzie implementacji klasy:

• lokalne deklaracje w taki sam sposób jak w nagłówku
• definicje funkcji zawsze (pełny kontrakt)
• definicje funkcji składowych zawsze (pełny kontrakt lub odniesienie do katalogu głównego wirtualnego zastąpienia)
• zmienne statyczne zdefiniowane, jeśli istnieją (cel dlaczego)

W nagłówku szablonu:

• powyższe połączyło się i
• odpowiednie / nieodpowiednie typy dla argumentów szablonów i
• jak dobrze przydatność jest wykrywana statycznie

Na private:początku sekcji prywatnej znajduje się cała dokumentacja, której użytkownicy powinni potrzebować.

Dokumentacja jest tego warta każdego dnia, pomaga w krótkim opisie przypadków użycia i historii. Jakkolwiek kod jest zrozumiały dla samego siebie, nie jest w stanie tak łatwo wyjaśnić biznesu, jak kilka linijek historii. Kod z pewnością wymagałby od użytkownika przestrzegania logiki, aby zrozumieć, co się dzieje. :-) Moje 2 centy ...

Zdecydowanie!

Ten kod powinien być samodokumentujący, jest hasłem, którego należy przestrzegać. Chciałbym jednak powiedzieć, że prywatny kod wymaga tyle samo dokumentacji, jeśli nie więcej, niż kod publiczny, ponieważ zazwyczaj tutaj zwykle przyjmuje się najwięcej założeń, tylko dlatego, że programista zakłada, że ​​pozostanie w ciemności . Kilka miesięcy później, kiedy pojawi się błąd, poświęcisz czas, próbując sobie przypomnieć, co napisał ten kod (być może sam).

Dokumentacja nie powinna być prezentem dla innych. Dokumentacja na wszystkich płaszczyznach (dobrze dobrane nazwy zmiennych, samok dokumentujące się nazwy klas, dobrze zorganizowany kod, odpowiednio segmentowane metody itp.) Jest darem dla każdego, kto może mieć kontakt z twoim kodem, włączając ciebie.