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

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

/**
 * (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) зарплату работника. Это просто кажется излишним. Теперь я мог видеть, что что-то более сложное, вы можете написать больше в (а) частях, чтобы дать контекст, но для большинства геттеров/сеттеров там формулировка почти точно такая же.

Мне просто интересно, если для простых getters/seters это нормально, чтобы заполнить либо (a) часть ИЛИ (b) часть.

Как вы думаете?

Ответ 1

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

Ответ 2

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

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

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

Ответ 3

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

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

Ответ 4

Как правило, ничего, если я могу помочь. Getters и seters должны быть понятны.

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

Ответ 5

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

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

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

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

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

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

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

Ответ 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).

Ответ 7

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

Для меня это преимущество само по себе стоит затраты.

Ответ 8

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

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

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

Ответ 9

Если в 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();

Ответ 10

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

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

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

Ответ 11

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

Ответ 12

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

Ответ 13

Не помещайте ничего, если имя поля достаточно подробно описано в содержании.

В общем, пусть код будет самостоятельным и избегать комментирования, если это вообще возможно. Для этого может потребоваться рефакторинг.

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

Ответ 14

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

Ответ 15

Если это геттер/сеттер, он должен быть документирован.

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