Czy powinieneś udokumentować wszystko, czy tylko większość?

22

Trochę kontrowersyjnym tematem wydaje się dokumentowanie wszystkiego, w tym składni geterów i setterów dla pól w języku „JavaBean”: ludzie mówią, że jest to niepotrzebnie długi i powtarzający się DRY (nie powtarzaj się) , że konwencja nazewnictwa powinna wszystko wyjaśniać , i zaśmieca kod / dokumentację. Czasami te argumenty działają. Ale innym razem kończy się to:

alternatywny tekst

Powyżej jest powszechne w projektach open source, które odważnie przestrzegają tych zasad. Pozostała Ci całkowicie bezużyteczna dokumentacja . To nie tłumaczy niczego, co dzieje się pod spodem, możliwych efektów, ani nawet oczekiwanej wartości (czy może być zerowa czy nigdy zerowa? Nie wiem; Javadoc mi nie mówi).

Kiedy powinienem dokumentować? Czy dokumentuję wszystko, nawet jeśli czasami zaśmieca kod? Czy też nic nie dokumentuję, ponieważ w moich oczach jest to „oczywiste”?

TheLQ
źródło
3
w pewnym stopniu pokazuje to problem z nazewnictwem, np. getDate powinno być getCreationDate lub getExpiryDate lub co kiedykolwiek ma sens w domenie. Oczywiście nazywanie nie jest panaceum.
jk.
Uwaga: pojawiło się to w kolejce weryfikacji CV. Myślę, że powinno być otwarte - pytanie dotyczy tematu (dokumentacja to SDLC), a odpowiedzi są naprawdę dobre i odpowiadają na pytanie w rozsądnej ilości miejsca (tj.

Odpowiedzi:

24

Dokumentuj wszystko , co ma sens, dokumentować .

W idealnym świecie tak, dokumentowałbyś wszystko. Jednak na Ziemi mamy terminy, filmy fabularne, rodziny i przyjaciół do odwiedzenia, wakacje do wzięcia, tylko 24 godziny na dobę i tylko 365 dni w roku. Po prostu nie ma wystarczająco dużo czasu, aby wszystko udokumentować. Optymalnie udokumentuj wszystko, co możesz (nie skończysz), ale uzyskaj jak najwięcej za swoje pieniądze:

  • Czytelny kod i podpisy metod powinny być tak oczywiste, jak to tylko możliwe, aby dokumentacja była mniej potrzebna.
  • Najpierw dokumentuj najbardziej niejasne rzeczy. Pomagaj innym, dokumentując szalone hacki, które musiałeś zrobić, aby wyciągnąć rzeczy z domu.
  • Udokumentuj, dlaczego przed czym - nie komentuj, co coś robi, na przykład „Iteruj po rekordach klientów, w których saldo jest mniejsze niż zero, a ocena jest mniejsza niż jeden, i dodaj je do listy zwolnionych klientów”. Udokumentuj, dlaczego dodajesz ich do listy zwykłym angielskim (lub językiem zespołu), np. „Ponieważ ci klienci mają ujemne saldo i niskie oceny, powodują, że tracimy pieniądze, więc wyklucz ich z możliwości dokonywania zakupów.
Ryan Hayes
źródło
27
Po pierwsze, udokumentuj wszystko, co NIE
MA
1
Dokumentowanie wszystkiego nie oznacza dokumentu słownego według metody. Może być tak mały jak komentarz. Dokumentowanie wszystkiego w sposób, który nie ma sensu, nie ma sensu, ale próba wyjaśnienia wszystkich niejasnych rzeczy dla osób, które są więcej niż minimalnie kompetentne, robi to.
Ryan Hayes,
1
@ysolik Zgadzam się, ale myślę, że miał na myśli „Dokumentuj wszystko , co ma sens, aby dokumentować”
Alan Pearce,
3
@Alan i @Ryan: komentarz nie miał zaprzeczać Ryanowi. To była tylko gra słów :) Tak przy okazji, zgadzam się ze wszystkim, co mówi Ryan, z wyjątkiem: „W idealnym świecie tak, wszystko byś dokumentował”. W idealnym świecie nie musisz niczego dokumentować, kod byłby samodokumentujący i wyjaśniający.
ysolik 10.10.10
1
@ysolik O rany, to byłby idealny świat idealny.
Ryan Hayes,
8

Dokumentuj dalej, aż zobaczysz, jak ktoś inny to czyta, bez potrzeby wyjaśniania czegokolwiek.

Brad Mace
źródło
6

W ubiegłym tygodniu był świetny artykuł na temat dokumentacji w The Daily WTF. Myślę, że mówi wszystko, więc zostawię link:

http://thedailywtf.com/Articles/Documentation-Done-Right.aspx

Zasadniczo mówi, że nie powinieneś dokumentować czegoś, jeśli nie będzie to przydatne (część dokumentacji pozostawia się do zgniszczenia w szufladzie) i dokumentować najmniejszą ilość informacji potrzebną do zrozumienia określonej części projektu. Zbyt dużo dokumentacji po prostu dezorientuje czytelnika.

Mike42
źródło
4

Naprawdę zależy od tego, jak czytelny jest kod dla czytelników, którzy go czytają. Dowiedz się, kim są odbiorcy czytający Twój kod i poproś, aby ktoś, kto spełnia ten profil, przeczytał Twój kod.

Innym podejściem byłoby sprawdzenie własnego kodu po tygodniu i sprawdzenie, czy nadal rozumiesz, co zrobiłeś, a jeśli nie, udokumentuj go i przejrzyj kod za około dwa tygodnie.

błędy
źródło
4

Doceniam przejrzystą i obszerną dokumentację, ale nie ma to jak kod samodokumentujący. Tak więc, dla mnie najważniejsze jest:

Bądź bardzo podejrzliwy w stosunku do dokumentacji (kodu źródłowego); spróbuj uczynić go zbędnym poprzez ulepszenie kodu, ale nie unikaj jasnego i kompletnego dokumentowania w razie potrzeby.

Oczywiście w pewnych okolicznościach dokumentacja może być wymagana z powodów innych niż „wyjaśnienie, co robi kod” (np. Duża baza zespołów, standardy organizacji itp.).

DLA
źródło
patrz także: „Komentarze to zapach kodu”
komik
2

Sugeruję w dokumentacji, że jeśli w kodzie jest coś fantazyjnego, należy on do dokumentu, który powinien być aktualizowany. Chciałbym, aby podlegało wielu interpretacjom, moim zdaniem jest to, gdy coś jest robione w określony sposób, który może mieć skutki uboczne, na które należy zwrócić uwagę, np. Coś można zrobić rekurencyjnie, aby upewnić się, że przedmioty wnuka są przetwarzane podczas przechodzenia przez drzewo węzłów wykonać test na wszystkich potomkach. Wyjaśnienie, dlaczego coś zostało zrobione w określony sposób, może być dobrym sposobem na sprawdzenie, czy istnieje dobry powód, aby coś użyć.

JB King
źródło
1

Mówiąc najprościej, dokumentacja ma pomóc deweloperom teraz, a opiekunom w przyszłości.

Jeśli pamiętasz tę prostą maksymę, poziom dokumentacji powinien być samookreślający.

Dokumentacja, ze względu na dokumentację, jest stratą czasu ... ale wyjaśnienie tego, co robisz, jest bardziej pomocne niż ktoś, kto będzie musiał dokonać inżynierii wstecznej twojego kodu za pięć lat.

Andrzej
źródło
0

Osobiście podchodzę do rozważania udokumentowania wszystkiego. Tzn. Podczas kodowania zastanawiam się w każdym momencie, czy dokumentacja może wnieść wartość dodaną. W większości przypadków odpowiedź brzmi „tak” dla dokładnie takich ograniczeń i wiedzy w dziedzinie, o której mowa w pierwotnym pytaniu. Np. Zdolność zerowa, unikalne ograniczenia, interpretacja pola w szerszej dziedzinie.

Aby uniknąć powielania, zwykle dokumentuję główne klasy API za pomocą tego rodzaju informacji. Następnie dokumentuj tylko implementacje i elementy wewnętrzne, w których zachowanie jest nieoczywiste lub niespójne. Uważam, że działa to dobrze, ponieważ to użytkownicy interfejsu API potrzebują największej pomocy i dokumentacji, ogólnie można bezpiecznie założyć, że osoby modyfikujące implementację znają interfejs API, więc mają tę wiedzę.

Mam również tendencję do dokumentowania tylko osób pobierających. Nie powielam dokumentacji na ustawieniach, definicjach pól i parametrach konstruktora. Dokumentuję tylko nieoczywiste zachowania, takie jak domyślne w tych miejscach. Każde zachowanie, które można wywnioskować z dokumentacji modułu pobierającego, nie jest udokumentowane. Na przykład, jeśli moduł pobierający jest udokumentowany jako nigdy nie zwracający wartości NULL, generalnie nie dokumentuję, że nie można przekazać wartości NULL ustawieniu, chyba że istnieje wartość domyślna.

Niektórzy ludzie lubią oznaczać ten akt „rozważania dokumentacji”, dodając puste komentarze tam, gdzie rozważali dokumentację, ale uznali ją za niepotrzebną. Nie podoba mi się ta praktyka, ponieważ po prostu zaśmieca kod i przeszkadza.

EdC
źródło