Комментарии простого геттера / сеттера

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

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

Что вы думаете?

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

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