Jakiej konwencji używasz do komentowania metod pobierających i ustawiających? To jest coś, nad czym zastanawiałem się od jakiegoś czasu, na przykład:
/**
* (1a) what do you put here?
* @param salary (1b) what do you put here?
*/
public void setSalary(float salary);
/*
* (2a) what do you put here?
* @return (2b)
*/
public float getSalary();
Zawsze uważam, że piszę dokładnie to samo dla 1a / bi 2a / b, coś w rodzaju 1a) Ustawia wynagrodzenie pracownika, 1b) wynagrodzenie pracownika. Po prostu wydaje się to zbyteczne. Teraz widzę, że w przypadku czegoś bardziej złożonego możesz napisać więcej w (a) częściach, aby nadać kontekst, ale dla większości pobierających / ustawiających elementy sformułowania są prawie dokładnie takie same.
Jestem po prostu ciekawy, czy dla prostych pobierających / ustawiających elementy można wypełnić tylko część (a) LUB część (b).
Co myślisz?
Odpowiedzi:
Zwykle po prostu wypełniam część param dla seterów i część @return dla getterów:
W ten sposób narzędzia sprawdzające javadoc (takie jak ostrzeżenia Eclipse) będą działać bezproblemowo i nie będzie duplikatów.
źródło
Absolutnie bezcelowe - lepiej będzie bez tego rodzaju bzdur zaśmiecających Twój kod:
Bardzo przydatne, jeśli jest to uzasadnione:
Zwłaszcza wyjaśnienie, co właściwie oznacza właściwość, może być kluczowe w modelach dziedzinowych. Ilekroć widzę fasolę pełną właściwości o niejasnych nazwach, które rozumieją tylko bankierzy inwestycyjni, biochemicy lub fizycy kwantowi, a komentarze wyjaśniają, że metoda setGobbledygook () „ustawia gobbledygook”, chcę kogoś udusić.
źródło
Generalnie nic, jeśli mogę na to poradzić. Getters i setters powinny być oczywiste.
Wiem, że to brzmi jak brak odpowiedzi, ale staram się wykorzystywać swój czas na komentowanie rzeczy, które wymagają wyjaśnienia.
źródło
Powiedziałbym tylko martwić się o komentowanie metod pobierających i ustawiających, jeśli mają jakiś efekt uboczny lub wymagają jakiegoś warunku wstępnego poza inicjalizacją (np .: pobranie usunie element ze struktury danych lub w celu ustawienia czegoś, czego potrzebujesz aby najpierw mieć x i y). W przeciwnym razie komentarze tutaj są dość zbędne.
Edycja: Dodatkowo, jeśli zauważysz wiele efektów ubocznych związanych z twoim getter / setter, możesz chcieć zmienić getter / setter, aby miał inną nazwę metody (np. Push and pop dla stosu) [Dzięki za komentarze poniżej]
źródło
Zadaj sobie pytanie, co chcesz, aby ludzie widzieli, gdy komentarze są wyświetlane jako dokumenty JavaDocs (z przeglądarki). Wiele osób twierdzi, że dokumentacja nie jest konieczna, ponieważ jest oczywista. To nie będzie obowiązywać, jeśli pole jest prywatne (chyba że jawnie włączysz JavaDocs dla pól prywatnych).
W Twoim przypadku:
Nie jest jasne, w czym jest wyrażone wynagrodzenie. Czy chodzi o centy, dolary, funty, RMB?
Podczas dokumentowania seterów / pobierających lubię oddzielić to, co jest od kodowania. Przykład:
Pierwsza linia mówi, że zwraca wysokość. Zwracany parametr dokumentuje wysokość w metrach.
źródło
public void setSalary(float aud)
(lub bardziej realistyczniepublic void setSalary(BigDecimal aud)
). Jeszcze lepiej, nieruchomość powinna być typuabstract class CurrencyAmount
, który z kolei ma właściwościjava.util.Currency currency
ijava.math.BigDecimal amount
. Większość programistów, z którymi pracowałem, jest strasznie leniwa z JavaDoc, ale egzekwowanie API w ten sposób sprawia, że jest to mniejszy problem.Dlaczego po prostu nie dołączą znacznika referencyjnego, który pozwoli Ci skomentować wartość pola i referencję z metod pobierających i ustawiających.
Aby dokumentacja dotyczyła metody pobierającej i ustawiającej, a także pola (jeśli włączone są prywatne javadoc).
źródło
Tego rodzaju schematu można uniknąć, korzystając z Projektu Lombok . Po prostu udokumentuj zmienną pola, nawet jeśli jest
private
, i pozwól adnotacjom Lombok wygenerować odpowiednio udokumentowane metody pobierające i ustawiające.Dla mnie sama ta korzyść jest warta kosztów .
źródło
Jestem naprawdę rozczarowany odpowiedziami mówiącymi, że kompleksowe dokumentowanie to strata czasu. Skąd klienci twojego API mają wiedzieć, że wywołana metoda
setX
jest standardowym ustawiaczem właściwości JavaBean, chyba że wyraźnie powiesz to w dokumentacji ?Bez dokumentacji dzwoniący nie miałby pojęcia, czy ta metoda ma jakieś skutki uboczne, poza tym, że trzymają kciuki za pozornie przestrzeganą konwencję.
Jestem pewien, że nie tylko ja tutaj miałem nieszczęście odkryć na własnej skórze, że metoda o nazwie
setX
robi o wiele więcej niż tylko ustawianie właściwości.źródło
setX
miały skutki uboczne inne niż oczekiwane, mogę rzeczywiście z całą pewnością stwierdzić, że nie jest to idealny świat.Jeśli w getterze / setterze nie ma specjalnej operacji, zwykle piszę:
Z Javadoc (z opcją prywatną):
i / lub
Z Doxygen (z opcją prywatnego ekstraktu):
źródło
{@see #salary}
jest nieprawidłowy w wygenerowanej dokumentacji.Komentowanie akcesorów, szczególnie jeśli nigdzie nie wykonują żadnych operacji, jest niepotrzebne i marnowanie palców.
Jeśli ktoś czytający Twój kod nie może tego zrozumieć
person.getFirstName()
zwraca imię osoby, powinieneś spróbować wszystkiego, co w twojej mocy, aby go zwolnić. Jeśli robi jakąś magię w bazie danych, rzuca kilkoma kostkami, dzwoni do Sekretarza Imion, aby uzyskać imię, Można bezpiecznie założyć, że jest to nietrywialna operacja i dobrze ją udokumentować.Jeśli, z drugiej strony,
person.getFirstName()
nie oddasz imienia osoby ... no cóż, nie jedźmy tam, dobrze?źródło
Nie umieszczaj niczego, jeśli nazwa pola wystarczająco opisuje zawartość.
Generalnie, niech kod będzie niezależny i unikaj komentowania, jeśli to w ogóle możliwe. Może to wymagać refaktoryzacji.
EDYCJA: Powyższe odnosi się tylko do metod pobierających i ustawiających. Uważam, że wszystko, co nie jest trywialne, powinno być odpowiednio javadoc'owane.
źródło
dobrze jest wypełnić część (b), zwłaszcza jeśli umieścisz komentarz przy deklaracji pola, wskazujący, o co w tym polu chodzi.
źródło
Jeśli javadoc nic nie dodaje, usuwam javadoc i używam automatycznie generowanych komentarzy.
źródło
Zawsze wypełniam oba. Dodatkowy czas spędzony na pisaniu jest znikomy, a ogólnie więcej informacji jest lepsze niż mniej.
źródło