javadoc @param przypisanie stałej wartości

Odpowiedz Nowy wątek
2019-09-11 15:07
0

Cześć,

muszę udokumentować cały projekt tłumacząc go przy okazji wszystko ok ale co chwile muszę tłumaczyć np:

/**
*@param customerId numer identyfikacyjny klienta
*/

czy można jakoś zapisać aby za każdym razem gdy ide trafi na tą zmienną automatycznie mi ja komentował ustawiona przeze mnie wartością ?>
używam kompilator Intellij może tam jest jakaś opcja lub istnieje możliwość zrobienia pliku ?

Pozostało 580 znaków

2019-09-12 07:27

Ja bym wygenerował jakoś szablony javadoc w całym projekcie, a potem Ctrl+Shift+R aby podmienić „@param clientId” na „@param clientId numer identyfikacyjny klienta”.

Zastanów się nad zmianą pracy. To, co szef kazał ci zrobić, to kompletny kretynizm. Pewnie jakiś biurokratyczny nonsens z narzuconymi z góry „standardami”. Wartość dodawanej na siłę dokumentacji javadoc jest prawie zawsze ujemna. Po jakimś czasie się to rozjedzie z rzeczywistością i jedyne, co zostanie, to linijki kodu, które będzie trzeba scrollować.

Dawno temu, jakiś audyt narzekał na zrozumiałość kodu i brak dokumentacji. I wtedy dodawaliśmy te javadoc, tak jakby to w czymkolwiek pomogło, byle się audyt odczepił. Oczywiście, audyt miał rację - kod był crapem. W sprawie dokumentacji należało raczej napisać jakiś dokument obrazujący typowy przepływ danych, strukturę pakietów, patterny, jak postawić środowisko, itp.

Pozostało 580 znaków

2019-09-12 08:21
4

Litości.
Chcesz udokumentować projekt?
Napisz krótkie README.md w głównym katalogu.(*)
Napisz testy pokazujące jak używać / np. End to end przypadki użycia, jeśli to aplikacja.

Nie pisz komentarzy w kodzie i javadocôw. Nie dość, że to obciach i znajdziesz wiele stron w sieci opisujących dlaczego, to jeszcze programista javy, najdalej po trzech latach pracy, i kilku rozczarowaniach, uczy się kompletnie ignorować komentarze. Serio, gdyby nie to, że do gita zaglądanją też laicy i juniorzy, to w javadocach trzymałbym prywatne hasła (jedyne ryzyko, że sam ich wtedy nie znajde).

Poszukaj więcej pod hasłem czysty kod, comments are code smell.

(*)-jeśli projekt to typowy javowy CRUD, gdzie większa część kodu to mappery z dto na business object, entity
(czy co tam jeszcze) to wystarczy, że w README.md napiszesz Przepraszam. (Ewentualnie sorry)

Uwaga: Komentarze są faktycznie przydatne w językach niskiego poziomu typu assembler.

Przy okazji:ambasada javac stanowczo protestuje przeciwko sformułowaniu kompilator intellij.


Bardzo lubie Singletony, dlatego robię po kilka instancji każdego.
edytowany 9x, ostatnio: jarekr000000, 2019-09-12 12:20
Przepraszam :D. - Michał Sikora 2019-09-13 19:04

Pozostało 580 znaków

Odpowiedz
Liczba odpowiedzi na stronę

1 użytkowników online, w tym zalogowanych: 0, gości: 1, botów: 0