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

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

/**
 * 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.", Я хочется кого-нибудь задушить.

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

EDIT: выше относится только к геттерам и сеттерам. Я считаю, что все нетривиальное должно быть правильно javadoc'Ed.