Простые комментарии Getter / Setter

Обычно я просто заполняю часть параметров для сеттеров и часть @return для геттеров:

/**
 * 
 * @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();

Таким образом, инструменты проверки javadoc (например, предупреждения Eclipse) будут чистыми и не будут дублироваться.

Абсолютно бессмысленно - вам будет лучше без этой чуши, загромождающей ваш код:

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

Очень полезно, если это необходимо:

/**
 * 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);

В частности, объяснение того, что на самом деле означает свойство, может иметь решающее значение в моделях предметной области. Всякий раз, когда я вижу боб, полный свойств с непонятными названиями, понятными только инвестиционным банкирам, биохимикам или квантовым физикам, и в комментариях объясняется, что метод setGobbledygook () «устанавливает тупик», я хочу кого-нибудь задушить.

В общем, ничего, если я могу помочь. Геттеры и сеттеры не требуют пояснений.

Я знаю, что это звучит как отказ от ответа, но я стараюсь использовать свое время, чтобы комментировать вещи, требующие объяснения.

Я бы сказал, что беспокоиться о комментировании геттеров и сеттеров можно только в том случае, если у них есть какой-то побочный эффект или требуется какое-то предварительное условие вне инициализации (например: получение удалит элемент из структуры данных или для того, чтобы установить что-то, что вам нужно чтобы сначала поставить x и y на свои места). В противном случае комментарии здесь излишни.

Изменить: Кроме того, если вы обнаружите, что в вашем геттере / сеттере задействовано много побочных эффектов, вы можете изменить геттер / сеттер, чтобы иметь другое имя метода (например, push и pop для стека) [Спасибо за комментарии ниже]

Спросите себя, что вы хотите, чтобы люди видели, когда комментарии просматриваются как JavaDocs (из браузера). Многие говорят, что документация не нужна, потому что это очевидно. Этого не будет, если поле является частным (если вы явно не включите JavaDocs для частных полей).

В твоем случае:

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

Непонятно, в чем выражается заработная плата. Это центы, доллары, фунты, юань?

При документировании сеттеров / геттеров мне нравится отделять что от кодировки. Пример:

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

Первая строка говорит, что возвращает высоту. В возвращаемом параметре указывается высота в метрах.

Почему бы им просто не включить тег ссылки, чтобы вы могли комментировать значение поля и ссылку из геттеров и сеттеров.

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

public String getFoo() {
  return foo;
}

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

Так что документация применима к методам получения и установки, а также к полю (если включены частные javadocs).

Этого шаблона можно избежать, используя Project Lombok. Просто задокументируйте переменную поля, даже если она private, и позвольте аннотациям Lombok генерировать правильно задокументированные методы получения и установки.

Для меня одно только это преимущество стоит затрат.

Я действительно разочарован ответами, в основном утверждающими, что полное документирование - пустая трата времени. Как клиенты вашего API должны знать, что метод с именем setX является стандартным средством установки свойств JavaBean, если вы не указали это четко в документации?

Без документации вызывающий абонент вообще не знал бы, имел ли метод какие-либо побочные эффекты, кроме скрещивания пальцев по поводу очевидного соблюдения соглашения.

Я уверен, что я не единственный здесь, кто имел несчастье узнать на собственном опыте, что метод с именем setX делает гораздо больше, чем просто устанавливает свойство.

Если в геттере / сеттере нет специальной операции, я обычно пишу:

С помощью Javadoc (с частным вариантом):

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

и / или

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

С Doxygen (с опцией частного извлечения):

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

/** @return #salary. */
public float salary();

Комментирование аксессуаров, особенно если они нигде не выполняют никаких операций, не нужно и бесполезно.

Если кто-то, читающий ваш код, не может понять, что person.getFirstName() возвращает имя человека, вы должны попробовать все, что в ваших силах, чтобы его уволили. Если он творит чудеса с базой данных, бросает несколько кубиков, вызывает секретаря по именам, чтобы узнать имя, можно с уверенностью предположить, что это нетривиальная операция, и хорошо ее задокументировать.

Если же, с другой стороны, ваш person.getFirstName() не возвращает имя человека ... ну, давайте не будем туда ходить, ладно?

Не указывайте ничего, если имя поля достаточно описывает содержимое.

В общем, пусть код будет самодостаточным, и по возможности избегайте комментариев. Это может потребовать рефакторинга.

РЕДАКТИРОВАТЬ: Вышеупомянутое относится только к геттерам и сеттерам. Я считаю, что все нетривиальное нужно должным образом оформить с помощью javadoc.

можно заполнить часть (b), особенно если вы добавите комментарий к объявлению поля, указывающий, что это за поле.

Если javadoc ничего не добавляет, я удаляю javadoc и использую автоматически сгенерированные комментарии.

Я всегда заполняю и то, и другое. Дополнительное время, затрачиваемое на набор текста, ничтожно, и в целом больше информации лучше, чем меньше.