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.
źródło
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:
W kodzie implementacji klasy:
W nagłówku szablonu:
źródło
Na
private:
początku sekcji prywatnej znajduje się cała dokumentacja, której użytkownicy powinni potrzebować.źródło
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 ...
źródło
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.
źródło