Nie wiem o innych środowiskach, ale jeśli chodzi o duże (często otwarte) projekty PHP napisane przez innych ludzi, phpXRef jest absolutnym narzędziem ratującym życie (szczególnie jeśli dokument jest umieszczony online i Google może go zindeksować).
Nawet źle skomentowany projekt może przynajmniej pomóc mi wyśledzić, gdzie rzeczy zostały zdefiniowane i gdzie są używane (na przykład podczas refaktoryzacji).
Dobrze skomentowane, powstałe strony tworzą idealną Biblię do bazy kodu (w każdym razie do moich zastosowań).
Co więcej, moje preferowane IDE automatycznie wygeneruje blok komentarzy (jeśli wpisuję / **), co dla mnie działa w przybliżeniu w 75%. To zdumiewające, jak wiele głupich rzeczy przestałem popełniać przez całe życie mojego programisty tylko dlatego, że musiałem wyjaśniać innym ludziom (i przyszłości mnie), co robię. Kiedy mój komentarz do generatora dokumentów jest większy niż metoda, zwykle oznacza to, że nie wypiłem wystarczającej ilości kawy i być może zechcę myśleć trochę bardziej.
Te same bloki komentarzy tworzą również tekst „pomocy” uzupełniania, aby zobaczyć dokładnie to, czego oczekiwano (przez innych programistów) podczas pisania wywołania funkcji. Jest to dla mnie ogromny wzrost wydajności (szczególnie w tych rzadkich przypadkach, w których inny pomocny programista napisał „na miłość boską, nie rób / nie rób X” - co może zaoszczędzić wiele bólu.
Nie mogę wystarczająco podkreślić, jak przydatne jest określenie oczekiwanych typów danych wejściowych w złożonych (i często źle nazwanych) projektach PHP oraz kolejności argumentów w rzadziej używanych metodach. Nawet z własnym kodem nie zawsze pamiętam, jakie argumenty podałem za czymś, czego nie dotknąłem od wieków.
W jednym przypadku oznaczało to, że źródłem powtarzających się problemów było to, że z jakiegoś powodu, który źle odbija się na poprzednich programistach, niektóre funkcje, a nawet stałe zostały zdefiniowane w ogromnej liczbie miejsc (z pewnym stopniem niespójności dla dodatkowej „zabawy”) . To był znak, by odejść od projektu.
W większych projektach, które rozpoczęły się, zanim dołączyłem, widzę, który programista (zakładając, że oznaczył plik klasy nazwą i adresem e-mail) utworzył klasę, a po prostu możliwość znalezienia odpowiedniego programu i rozmowy z nim jest niezwykle pomocna.
Automatyczne listy zadań - użycie tagu @todo (powszechnego w projektach, w których pracuję) oznacza, że dokumentacja może śledzić rzeczy, które wymagają więcej pracy (lub funkcji, o których wiadomo, że ich brakuje). Ponownie moje IDE śledzi to i to samo służy jako dobry przewodnik, co najpierw wymaga mojej uwagi.
Wreszcie (i to dla mnie bardzo ważne) eliminuje to trywialny narzut związany z pisaniem tego wszystkiego, a następnie próbą aktualizowania go, gdy niektórzy (czytający wielu) koderzy dokonują zmian i nie rozmawiają z opiekunami dokumentacji.
Przyczyny obejmują:
- Oszczędzając później programistom stos czasu,
- Śledzenie, gdzie funkcje są wywoływane (i definiowane),
- Wykrywanie głupiego kodowania,
- Znajdowanie (jak zauważył inny), gdy czegoś oczywiście brakuje,
- Uproszczenie refaktoryzacji (nigdy dużo zabawy)
- (W wielu przypadkach) uzyskanie pomysłu na to, co programista próbował zrobić (zakładając, że zostawił kilka notatek).
- Jeśli projekt jest na tyle skomplikowany, że działa wiele licencji (bez zabawy), mogę szybko sprawdzić, które licencje dotyczą danej sekcji. Trzeba przyznać, że jest to bonus dodatkowy.
- Dowiedz się, z kim porozmawiać o pliku projektu.
- Automatyczne listy zadań
Nie lekceważ też wartości, jaką daje zadowolenie spiczastych włosów szefów za naciśnięciem jednego przycisku.
W skrócie, „automatyczne komentarze do dokumentacji” są niezbędne dla moich nawyków kodowania. Jestem pewien, że wielu uważa, że to kiepskie, ale jestem również pewien, że jest całkiem sporo ludzi, którzy dokładnie wiedzą, co mówię. Nie wiem, jak przetrwałem, zanim odkryłem phpXRef (i moje ulubione IDE).