Mam dość dużą prywatną bazę kodów, która ewoluowała od około dziesięciu lat. Nie używam phpDocumentor, ale odkąd używanie sekcji docblock stało się całkiem standardem w projektach open source, zaadaptowałem pisanie docblocków dla wszystkich metod publicznych w moim repozytorium. Większość bloków zawiera tylko krótki opis i wskazówki dotyczące wszystkich parametrów i typu zwracanego tekstu.
Wraz z pojawieniem się analizy statycznej te wskazówki pomogły mi w znalezieniu niespójności i możliwych błędów. Ostatnio przekonwertowałem całą bazę kodu (teraz działającą na PHP7.2), aby wszystkie parametry i zwracały wartości podpowiedzi, o ile to możliwe, przy użyciu wskazówek PHP. A teraz zastanawiam się ... Czy te druki typu docblock nie są zbędne? To wymaga sporo pracy, aby zsynchronizować wszystkie docbloki z ciągle zmieniającym się kodem, a ponieważ nie dodają one żadnych nowych informacji, zastanawiam się, czy lepiej je całkowicie usunąć, czy nie.
Z jednej strony usuwanie dokumentacji jest złe, nawet jeśli jest zbędne. Z drugiej strony naprawdę mam ochotę przełamać zasadę „nie powtarzać”, co jest typowe dla podpowiedzi.
Odpowiedzi:
Informacje, które można znaleźć w kodzie, nie powinny być powielane w komentarzach.
W najlepszym wypadku marnowanie wysiłku na utrzymanie ich synchronizacji. Bardziej prawdopodobne jest, że ostatecznie zsynchronizują się. W tym momencie są po prostu mylące.
Jeśli spojrzysz na równoważnik DocBlock w językach o typie statycznym (np. Java, C #), zauważysz, że komentarze do dokumentu nie zawierają informacji o typie. O ile dotyczy to twojego kodu PHP, radzę postępować podobnie. Oczywiście tam, gdzie nie można zastosować podpowiedzi typu, komentarz jest nadal najlepszą alternatywą.
Nie dotyczy to PHP, ale powielone informacje o typie mogą mieć sens, gdy typ jest domyślnie wywnioskowany (np. Haskell).
źródło
Tak, docblocks stały się zbędne w przypadku php 7.
Większość czasu na kodowanie spędza na czytaniu, więc dwukrotne czytanie tego samego wpływa na produktywność. Ponadto ułatwia pominięcie naprawdę ważnych komentarzy.
Nie piszę już docblocków, z wyjątkiem sytuacji, gdy chcę wpisać podpowiedź do tablicy określonego typu (np.
@return int[]Lub@param SomeStatus[] $statusList) lub gdy chcę dodać komentarz na temat metody, parametrów lub wartości zwracanej. Uważam, że ważne jest wyłączenie inspekcji phpstorm, która uruchamia się, gdy nie masz wszystkich parametrów i zwraca typy w docblock, jeśli masz docblock.źródło
Kod i dokumentacja zazwyczaj mają różnych odbiorców: dokumentacja jest dla użytkowników tej funkcji. Nie powinni patrzeć na kod, aby zrozumieć typy. Dlatego dokumentacja powinna zawierać wszystkie niezbędne informacje, w tym typy.
W niektórych systemach nie jest konieczne określanie typu parametru w dokumentacji, ponieważ typ można pobrać z kodu. PHPDoc nie jest takim systemem. Zamiast tego,
@paramznacznik jest udokumentowane , że„Dość dużo pracy, aby zsynchronizować wszystkie docbloki z ciągle zmieniającym się kodem” zostało nieco zmniejszone, ponieważ PHPDoc sprawdzi wskazówki dotyczące typów dokumentacji w stosunku do wskazówek dotyczących typu kodu. Jest to rodzaj analizy kłaczków / analizy statycznej, dlatego włącz generowanie dokumentacji do zautomatyzowanego procesu testowego.
Innym pytaniem, które możesz sobie zadać, jest to, dlaczego funkcje te są szczegółowo opisane, gdy „ciągle się zmieniają”. Zwykle motywacją jest stworzenie podręcznika HTML dla twoich interfejsów. Ale jeśli dokumentacja nigdy nie jest czytana poza środowiskiem IDE lub jeśli nie masz stabilnych interfejsów, w których dokumentacja ma sens, szczegółowe bloki dokumentów nie są konieczne, a nawet wprowadzają w błąd. Lepiej jest napisać tylko podsumowanie i odłożyć pełne dokumenty, aż do uzyskania stabilnego projektu.
źródło