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

Question

Какое соглашение вы используете, чтобы комментировать геттеры и сеттеры? Это то, что я удивляюсь довольно долго, например:

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

Я всегда нахожу, что в значительной степени пишу одно и то же для 1a / b и 2a / b, что-то вроде 1a) Устанавливает зарплату работника, 1b) зарплату работника. Это просто кажется излишним. Теперь я мог бы увидеть что-то более сложное, вы могли бы написать больше в (а) частях, чтобы дать контекст, но для большинства получателей / установщиков там почти такая же формулировка.

Мне просто любопытно, если для простых получателей / установщиков нормально заполнять только часть (a) ИЛИ часть (b).

Что ты думаешь?

Answer 1

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

/**
 * 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 () «устанавливает gobbledygook.», Я хочу задушить кого-то.

Answer 2

Я обычно просто заполняю часть параметра для сеттеров, а часть @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) будут чистыми, и при этом не будет дублирования.

Answer 3

Вообще ничего, если я могу помочь. Методы получения и установки должны быть самоочевидными.

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

Answer 4

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

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

Answer 5

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

В вашем случае:

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

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

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

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

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

Answer 6

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

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

public String getFoo() {
  return foo;
}

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

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

Answer 7

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

Для меня одно это вознаграждение стоит затрат .

Answer 8

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

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

Answer 9

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

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

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

Answer 10

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

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

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