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

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:

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”?

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.

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

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.

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.

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.).

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ć.

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.

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.