Proste komentarze Getter / Setter

125

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?

ThaDon
źródło
54
Na marginesie, nie używaj zmiennoprzecinkowej do niczego pieniężnego (takiego jak wynagrodzenie tutaj), nigdy. Patrz np stackoverflow.com/questions/965831/...
Jonik
3
Zamiast tego użyj BigDecimal.
Josep

Odpowiedzi:

84

Zwykle po prostu wypełniam część param dla seterów i część @return dla getterów:

/**
 * 
 * @param salary salary to set (in cents)
 */
public void setSalary(float salary);

/**
 * @return current salary (in cents, may be imaginary for weird employees)
 */
public float getSalary();

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.

sleske
źródło
Czy możesz naprawić literówkę? „@return part for setters”
Jonik
1
W komentarzu dotyczącym wynagrodzenia () jest również literówka. To nie jest komentarz JavaDoc.
Fostah
1
Zgadzam się, że to najlepsze podejście do komentowania akcesorów.
Fostah
31
Wydaje mi się, że dodawanie szumu do kodu w celu uciszenia nadmiernie pedantycznego ostrzeżenia z naszych narzędzi jest dla mnie niewłaściwe. Jeśli nie wnosi to wartości do programisty, właściwym rozwiązaniem byłoby zmniejszenie / poprawienie szczegółowości narzędzi i / lub zmniejszenie tego, jak bardzo zależy nam na przeskakiwaniu przez przeszkody, aby narzędzia nas wynagrodziły. Narzędzia analityczne mają nam pomagać i oszczędzać wysiłek, a nie tworzyć dla nas więcej bezsensownych zadań.
Lyle
1
@Lyle To może być prawda, ale wydaje mi się, że prawie zawsze jest coś użytecznego, co programista może powiedzieć, co lepiej opisuje metodę pobierającą / ustawiającą niż samą sygnaturę metody. Tak, są przypadki, w których programista jest leniwy i po prostu powtarza podpis metody w komentarzu, ale myślę, że ogólnie rzecz biorąc, wymuszenie jest pomocne.
Matt Vukas,
174

Absolutnie bezcelowe - lepiej będzie bez tego rodzaju bzdur zaśmiecających Twój kod:

/**
 * Sets the foo.
 * 
 * @param foo the foo to set
 */
public void setFoo(float foo);

Bardzo przydatne, jeśli jest to uzasadnione:

/**
 * Foo is the adjustment factor used in the Bar-calculation. It has a default
 * value depending on the Baz type, but can be adjusted on a per-case base.
 * 
 * @param foo must be greater than 0 and not greater than MAX_FOO.
 */
public void setFoo(float foo);

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ć.

Michael Borgwardt
źródło
2
Uważam dokładnie, najgorsze są modele dziedzinowe, w których tylko ekspert dziedzinowy wie, co do cholery oznacza ta własność.
ThaDon
7
Nawet jeśli jest to przydatne, co byś zrobił dla getFoo (). Czy skopiujesz ten sam komentarz również dla funkcji getFoo ()?
Vinoth Kumar CM,
3
@cmv: Oczywiście część „param” nie zostanie skopiowana. Nie jestem pewien, czy wartość dołączenia informacji do obu metod dostępu bezpośrednio uzasadnia powielanie informacji. Prawdopodobnie tak. Jeszcze lepszy byłby sposób na dołączenie jednego komentarza do obu; Wierzę, że jest to dostępne w Projekcie Lombok.
Michael Borgwardt
@VinothKumar: może lepiej byłoby po prostu wyjaśnić właściwość w funkcji pobierającej (tak jak w „Foo jest współczynnikiem korygującym używanym w obliczeniach słupka”) i skutki zmiany wartości w metodzie ustawiającej (lub czy jest to konieczne lub nie, aby zainicjować tę wartość - w przykładzie odpowiedzi nie jest konieczne inicjowanie Foo, ponieważ „ma wartość domyślną zależną od typu Baz”).
freitass
+1 dla „niejasnych nazw, które rozumieją tylko bankierzy inwestycyjni, biochemicy lub fizycy kwantowi”
Jackson
36

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.

Eric Wendelin
źródło
5
Inną poprawną odpowiedzią w tym zakresie może być „projekty z getterami i ustawiaczami nie rozumieją właściwie pojęcia hermetyzacji” :)
Trejkaz
2
@Trejkaz: Nieprawda, ponieważ metody akcesorów dopuszczają właściwości tylko do odczytu lub tylko do zapisu, a także na polimorfizm (a więc zawijanie, proxy itd.).
Laurent Pireyn,
2
Mogą na to zezwalać, ale często wzorzec konstruktora może zastąpić setery (mniej zmienny) lub wzorzec odwiedzających może zastąpić
metody pobierające
Z pewnością podoba mi się wzorzec budujący i używam go, ale jest tak wiele wsparcia dla POJO (np. W Hibernate), że gettery i setery wciąż mają swoje bardzo ważne miejsce, na dobre lub na złe. To najgorsza rzecz w Javie, IMHO i po pisaniu powtarzających się JavaDocs przez ponad dekadę, jestem prawie gotowy, aby zasubskrybować porady @ sleske.
Michael Scheper
34

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]

Gopherkhan
źródło
10
prawdopodobnie powinieneś zmienić nazwy getterów, które mają skutki uboczne, aby były bardziej przejrzyste, ponieważ nie wszyscy programiści będą czytać komentarze.
akf
W porządku - ale wymaga to od użytkowników twojego API, aby wiedzieli, że gdyby wystąpiły jakiekolwiek skutki uboczne, zostałyby udokumentowane !
oxbow_lakes
akf, właśnie tak myślałem po wysłaniu :) Chyba dodam to do mojej odpowiedzi.
Gopherkhan
1
ale jeśli nie dokumentujesz "głupich" metod pobierających i ustawiających (ja też to wolę!) - jak pozbyć się ostrzeżeń Eclipse o braku javadoc? Nie chcę zaśmiecać mojego obszaru roboczego takimi ostrzeżeniami, ale nie chcę też, aby to ostrzeżenie było wyłączone dla wszystkich innych metod ...
Zordid,
12

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:

public void setSalary(float s)
public float getSalary()

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:

/**
 * Returns the height.
 * @return height in meters
 */
public double getHeight()

Pierwsza linia mówi, że zwraca wysokość. Zwracany parametr dokumentuje wysokość w metrach.

Steve Kuo
źródło
1
chociaż zgadzam się z tobą, myślę, że należy się upewnić, że komentarze funkcji nie przedstawiają złej wybranej, nieokreślonej nazwy funkcji.
karlipoppins
Jestem wielkim zwolennikiem JavaDocs, ale także wielkim zwolennikiem samodokumentującego się kodu. Więc przynajmniej dla rozgrywającego zrobiłbym coś takiegopublic void setSalary(float aud) (lub bardziej realistycznie public void setSalary(BigDecimal aud)). Jeszcze lepiej, nieruchomość powinna być typu abstract class CurrencyAmount, który z kolei ma właściwości java.util.Currency currencyi java.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.
Michael Scheper
Jeśli jednostka jest jednostką SI, np. Metry / sekundy, nie ma potrzeby dokumentowania, jeśli nie jest to jednostka Si, należy ją udokumentować lub lepiej nazwać, aby uwzględnić niestandardową jednostkę, np. Wysokość Stopy
AlexWien
8

Dlaczego po prostu nie dołączą znacznika referencyjnego, który pozwoli Ci skomentować wartość pola i referencję z metod pobierających i ustawiających.

/**
* The adjustment factor for the bar calculation.
* @HasGetter
* @HasSetter
*/
private String foo;

public String getFoo() {
  return foo;
}

public void setFoo() {
  this foo = foo;
}

Aby dokumentacja dotyczyła metody pobierającej i ustawiającej, a także pola (jeśli włączone są prywatne javadoc).

Steve
źródło
Zgadzam się. I wtedy zdałem sobie sprawę, po co w ogóle pisać te wszystkie schematy? Zobacz moją odpowiedź na temat Projektu Lombok.
Michael Scheper,
7

Tego rodzaju schematu można uniknąć, korzystając z Projektu Lombok . Po prostu udokumentuj zmienną pola, nawet jeśli jestprivate , i pozwól adnotacjom Lombok wygenerować odpowiednio udokumentowane metody pobierające i ustawiające.

Dla mnie sama ta korzyść jest warta kosztów .

Michael Scheper
źródło
4

Jestem naprawdę rozczarowany odpowiedziami mówiącymi, że kompleksowe dokumentowanie to strata czasu. Skąd klienci twojego API mają wiedzieć, że wywołana metoda setXjest 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 setXrobi o wiele więcej niż tylko ustawianie właściwości.

oxbow_lakes
źródło
11
Bez dokumentacji każdy wywołujący założyłby, że metoda o nazwie setX ustawia X. Wynika z tego, że jeśli setX faktycznie ustawia X, nie robiąc nic ważnego, to nie potrzebujesz dokumentacji.
mqp
To wspaniale! Czy ta firma CrudTech, której API koduję, postępuje zgodnie z twoją konwencją, czy też podąża za czyjąś inną w tym wątku? Hmmmm
oxbow_lakes
5
Nie ma sensu pisać „ustala cenę” w dokumencie setPrice, jeśli metoda tylko ustala wartość właściwości price, ale jeśli np. Aktualizuje również właściwość totalPrice i przelicza podatek, takie zachowanie powinno oczywiście zostać udokumentowane.
João Marcus
8
Wydaje się, że prosisz o dokumentację stwierdzającą: „Robi to, czego oczekujesz”. To trochę tak, jak napisanie „Uwaga: GORĄCO” na filiżance kawy. W idealnym świecie nie byłoby potrzeby mówić takich rzeczy.
Kevin Panko,
1
Tak - po użyciu interfejsów API, w których metody zwane rzeczami, takie jak, setXmiały skutki uboczne inne niż oczekiwane, mogę rzeczywiście z całą pewnością stwierdzić, że nie jest to idealny świat.
oxbow_lakes
4

Jeśli w getterze / setterze nie ma specjalnej operacji, zwykle piszę:

Z Javadoc (z opcją prywatną):

/** Set {@see #salary}. @param {@link #salary}. */
public void setSalary(float salary);

i / lub

/** 
 * Get {@see #salary}.
 * @return {@link #salary}.
 */
public float salary();

Z Doxygen (z opcją prywatnego ekstraktu):

/** @param[in] #salary. */
public void setSalary(float salary);

/** @return #salary. */
public float salary();
TermWay
źródło
2
Problem z tym podejściem polega na tym, że Javadoc domyślnie nie generuje prywatnej dokumentacji! W takim przypadku tag referencyjny {@see #salary}jest nieprawidłowy w wygenerowanej dokumentacji.
Jarek Przygódzki
1

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?

Henrik Paul
źródło
6
Co się stanie, jeśli getFirstName () zwróci wartość null? Gdzie byłoby to udokumentowane?
Steve Kuo
A co z security.getFinalMaturity ()? Nie wszystkie nazwy nieruchomości mają natychmiast zrozumiałe znaczenie. Czy chciałbyś zostać zwolniony za to, że nie wiesz, co to znaczy?
Michael Borgwardt
Co jeśli metoda jest implementowana przez swizzling? Skąd masz to wiedzieć, jeśli nie zostało to jasno udokumentowane? Skąd masz wiedzieć, że to ustawiacz standardów, chyba że doktor mówi, że tak jest?
oxbow_lakes
2
Metoda get / set powinna moim zdaniem być zarezerwowana dla metod pobierających i ustawiających. Wyszukiwania bazy danych powinny nazywać się mniej więcej „lookupPerson”.
Thorbjørn Ravn Andersen
1

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.

Thorbjørn Ravn Andersen
źródło
1
Istnieje różnica między komentowaniem a dokumentowaniem.
Tom Hawtin - tackline
1
Bardzo prawdziwe. Właśnie dlatego nie komentuję metod pobierających i ustawiających. Powinny być oczywiste, a dodanie komentarza wskazuje, że kod nie jest zrozumiały.
Thorbjørn Ravn Andersen
0

dobrze jest wypełnić część (b), zwłaszcza jeśli umieścisz komentarz przy deklaracji pola, wskazujący, o co w tym polu chodzi.

akf
źródło
Niedobrze - ludzie nie czytają komentarzy w terenie. Javadoc nie generuje nawet domyślnie dokumentacji prywatnej, a środowiska IDE nie wyświetlają dokumentacji pola, gdy używasz szybkiej pomocy w wywołaniu metody.
Trejkaz
ludzie nie czytają komentarzy w terenie, chyba że muszą. Kiedy zajdzie taka potrzeba, im więcej informacji, tym lepiej.
akf
0

Jeśli javadoc nic nie dodaje, usuwam javadoc i używam automatycznie generowanych komentarzy.

Alex B.
źródło
0

Zawsze wypełniam oba. Dodatkowy czas spędzony na pisaniu jest znikomy, a ogólnie więcej informacji jest lepsze niż mniej.

Paul Sonier
źródło
Nie wymagają wyjaśnienia tylko wtedy, gdy powiesz „to jest ustawiacz właściwości”. W przeciwnym razie klient API nie ma pojęcia, co tak naprawdę dzieje się w metodach
oxbow_lakes
1
Kto powiedział coś o tym, co nie wymaga wyjaśnień?
Paul Sonier