Proste komentarze Getter / Setter

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?

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.

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

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.

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]

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.

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

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 .

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.

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();

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?

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.

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

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

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