To pytanie ma już tutaj odpowiedzi :
Komentarze
Odpowiedź
Powinieneś udokumentować:
i
- co nie może bądź oczywiste, jak.
Dlaczego zoptymalizowałeś ten bit, do czego dokładnie służy ten skrót, jakiego wyniku oczekujesz, jakie są wymagania, dlaczego tam jest po pierwsze, skąd wysyłane są te dane, skąd bierzesz dane wejściowe, jeśli jest to wielowątkowe, wyjaśnij model, jeśli istnieje baza danych, wyjaśnij schemat, linki, dlaczego …
Nie dokumentuj tego, co oczywiste. Jeśli chodzi o prezentację, można to zrobić na wiele różnych sposobów. Osobiście lubię komentarze w tekście (jestem starszym typem programisty i nie mieliśmy wtedy wyszukanych narzędzi). po prostu znajdź to proste i nieskomplikowane). Jeśli chcesz czegoś wymyślnego, upewnij się, że nie zajmuje to zbyt dużo czasu, w przeciwnym razie bardzo prawdopodobne, że wkrótce to porzucisz.
Komentarze
Odpowiedź
Przeczytaj własny kod, który napisałeś 2 lub więcej lat temu.
Zadaj sobie pytanie, jakiego rodzaju rzeczy są niejasne, i zostaw sobie drapanie w głowie po przeczytaniu. Tego typu rzeczy (cokolwiek by to nie było, będą różne dla różnych programistów) są tym, co chcesz zacząć dokumentować jako pierwszy w przypadku każdego nowego kodu, który opracujesz, lub starego kodu, który przepisujesz / ponownie używasz. Każde formatowanie, które spowalnia zrozumienie , zmień.
Albo za 2 lata …
Odpowiedź
Jedna rzecz, którą powinieneś include to zależności. Jeśli funkcja opiera się na czymś z tam , to doc co to jest, gdzie tam jest i dlaczego.
Odpowiedź
Ponieważ „używasz PHP, PHPDoc byłoby dobrym miejscem do rozpoczęcia. Możesz zbudować dokumentację API bezpośrednio w źródle, a następnie użyć tego samego formatu do pisania samouczków i dokumentacji użytkownika. Uzyskasz także pewną elastyczność, jeśli chodzi o format wyjściowy.
Odpowiedź
Zawsze zaczynam pisać kod, pisząc najpierw swoje komentarze. Opisz przebieg programu, a zaczniesz zdawać sobie sprawę, co wymaga komentarza, a co nie. Po rozpoczęciu pisania kodu upiększasz części, które wymagają dodatkowego wyjaśnienia, i udoskonalasz części, które są samodokumentujące.
Po zakończeniu każdej klasy, funkcji lub metody wracam i dodaję komentarze dla generatora dokumentów, takiego jak doxygen lub PHPDoc. W ten sposób uzyskasz rzeczywistą dokumentację API.
W zależności od tego, kto korzysta z mojego kodu, napiszę formalny opis dokumentu operacji w języku LaTeX lub Word.
Odpowiedź
Doxygen obsługuje większość języków. Będziesz musiał poświęcić trochę czasu na zrozumienie składni, ale głównym problemem jest to, co należy udokumentować. Traktuj każdą funkcję jako czarną skrzynkę. Dokumentuj, co wchodzi i co wychodzi. Dokumentuj, jakie błędy przechwytuje, czy argumenty mogą być zerowe, czy może zwrócić wartość null.
Pamiętaj, że za kilka miesięcy nie będziesz w stanie dowiedzieć się, co, do cholery, robi funkcja. Po prostu oszczędzasz czas.