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

125

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

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

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

ThaDon
источник
54
Кроме того, пожалуйста, никогда не используйте float для каких-либо денежных показателей (например, зарплаты). См., Например, stackoverflow.com/questions/965831/…
Jonik
3
Вместо этого используйте BigDecimal.
Josep

Ответы:

84

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

sleske
источник
Вы можете исправить опечатку? «@return part для сеттеров»
Jonik
1
Также есть опечатка в комментарии salary (). Это не комментарий JavaDoc.
Fostah
1
Я согласен, что это лучший подход к комментированию аксессуаров.
Fostah
31
Мне кажется неправильным добавлять шум в ваш код, чтобы заглушить чересчур педантичные предупреждения от наших инструментов. Если это не добавляет ценности программисту, то правильным решением было бы уменьшить / исправить многословие инструментов и / или уменьшить то, насколько мы заботимся о прыжках через обручи, чтобы инструменты вознаграждали нас. Инструменты анализа призваны помогать нам и экономить силы, а не создавать для нас более бессмысленные задачи.
Lyle
1
@Lyle Это может быть правдой, но я чувствую, что почти всегда есть что-то полезное, что программист может сказать, что описывает геттер / сеттер лучше, чем просто сигнатура метода. Да, бывают случаи, когда программист ленив и просто повторяет сигнатуру метода в комментарии, но я думаю, что, вообще говоря, принудительное поведение полезно.
Мэтт Вукас,
174

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

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

Майкл Боргвардт
источник
2
По моему мнению, хуже всего являются модели, специфичные для предметной области, где только эксперт в предметной области знает, что, черт возьми, означает свойство.
ThaDon
7
Даже если это полезно, что бы вы сделали для getFoo (). Скопируете ли вы тот же комментарий для getFoo ()?
Винот Кумар CM
3
@cmv: Очевидно, что часть "param" не будет скопирована. Я не уверен, оправдывает ли ценность наличия информации, прикрепленной к обоим аксессорам, прямое дублирование информации. Возможно - да. Еще лучше было бы прикрепить один комментарий к обоим; Я считаю, что это доступно в Project Lombok.
Майкл Боргвардт
@VinothKumar: может быть, было бы лучше просто объяснить свойство в геттере (например, «Foo - коэффициент настройки, используемый в вычислении Bar») и эффекты изменения значения в сеттере (или если это необходимо или не инициализировать это значение - в примере ответа инициализировать Foo необязательно, поскольку «он имеет значение по умолчанию в зависимости от типа Baz»).
freitass
+1 за «непонятные имена, которые понимают только инвестиционные банкиры, биохимики или квантовые физики»
Джексон
36

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

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

Эрик Венделин
источник
5
Еще один верный ответ в этом направлении может быть: «проекты с геттерами и сеттерами неправильно понимают понятие инкапсуляции» :)
Trejkaz
2
@Trejkaz: Неправда, потому что методы доступа допускают свойства только для чтения или только для записи, а также для полиморфизма (и, следовательно, обертывания, проксирования и т. Д.).
Laurent Pireyn
2
Они могут допускать эти вещи, но часто шаблон построителя может заменить сеттеры (менее изменчивый), или шаблон посетителя может заменить геттеры (более гибкий).
Trejkaz
Я, конечно, люблю и использую шаблон построителя, но существует настолько большая поддержка POJO (например, в Hibernate), что геттеры и сеттеры по-прежнему занимают свое очень важное место, как бы там ни было. Это самое опасное в Java, ИМХО, и после того, как я писал повторяющиеся JavaDocs в течение более десяти лет, я почти готов подписаться на совет @sleske.
Майкл Шепер
34

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

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

Gopherkhan
источник
10
возможно, вам следует изменить имена геттеров, у которых есть побочные эффекты, чтобы они были более понятными, поскольку не все разработчики будут читать комментарии.
akf
Это нормально, но для этого требуется, чтобы пользователи вашего API знали, что если бы были какие-либо побочные эффекты, они были бы задокументированы !
oxbow_lakes
akf, я именно об этом подумал после публикации :) Думаю, добавлю в свой ответ.
Gopherkhan
1
но если вы не документируете «тупые» геттеры и сеттеры (это то, что я тоже предпочитаю!) - как избавиться от предупреждений Eclipse об отсутствии документации javadoc? Я не хочу загромождать свое рабочее пространство подобными предупреждениями, но я также не хочу, чтобы это предупреждение
отключалось
12

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

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

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

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

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

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

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

Стив Куо
источник
1
Хотя я согласен с вами, я думаю, что нужно убедиться, что комментарии к функциям не соответствуют неверно выбранному, неявному имени функции.
karlipoppins
Я большой сторонник JavaDocs, но также большой сторонник самодокументирующегося кода. Так что, по крайней мере, для сеттера я бы сделал что-то вроде public void setSalary(float aud)(или более реалистично public void setSalary(BigDecimal aud)). Еще лучше, свойство должно быть типа abstract class CurrencyAmount, которое, в свою очередь, имеет свойства java.util.Currency currencyи java.math.BigDecimal amount. Большинство разработчиков, с которыми я работал, ужасно ленивы с JavaDoc, но применение подобного API делает это менее проблематичным.
Майкл Шепер
Если единица измерения - это единица СИ, такая как метры / секунды, нет необходимости документировать, если это не единица Si, тогда она должна быть задокументирована или лучше названа, чтобы включать нестандартную единицу, например, heightFeet
AlexWien
8

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

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

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

Майкл Шепер
источник
4

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

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

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

oxbow_lakes
источник
11
Без документации любой вызывающий будет предположить, что метод с именем setX устанавливает X. Из этого следует, что если setX действительно устанавливает X, не делая ничего другого важного, тогда вам не нужна документация.
mqp
Замечательно! Теперь эта компания CrudTech, чей API я кодирую, следует вашему соглашению, или она следует за кем-то еще в этой теме? Хмммм
oxbow_lakes
5
Нет смысла писать «устанавливает цену» в документе setPrice, если метод просто устанавливает значение для свойства price, но если он также, например, обновляет свойство totalPrice и пересчитывает налог, такое поведение, очевидно, должно быть задокументировано.
João Marcus
8
Кажется, вы просите в документации указать: «Это именно то, что вы ожидаете». Это немного похоже на надпись «Внимание: ГОРЯЧЕЕ» на чашке кофе. В идеальном мире не было бы нужды говорить такие вещи.
Кевин Панко
1
Да, используя API, в которых методы, называемые вещами вроде, setXимели побочные эффекты, отличные от ожидаемых, я действительно могу с уверенностью сказать, что это не идеальный мир.
oxbow_lakes
4

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

С помощью 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();
TermWay
источник
2
Проблема с этим подходом в том, что Javadoc по умолчанию не генерирует частную документацию! В этом случае ссылочный тег {@see #salary}недействителен в сгенерированной документации.
Jarek Przygódzki
1

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

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

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

Хенрик Пол
источник
6
Что, если getFirstName () вернет null? Где это было бы задокументировано?
Steve Kuo,
Как насчет security.getFinalMaturity ()? Не все названия свойств имеют понятное значение. Хотели бы вы, чтобы вас уволили за то, что вы не знаете, что это значит?
Майкл Боргвардт,
Что делать, если метод реализован путем свиззлинга? Откуда вы можете это знать, если это не было четко задокументировано? Откуда вы должны знать, что это установщик стандартов, если это не указано в документе?
oxbow_lakes
2
get / set, на мой взгляд, следует зарезервировать для геттеров и сеттеров. Поиск в базе данных должен называться «lookupPerson» или так.
Thorbjørn Ravn Andersen,
1

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

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

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

Торбьёрн Равн Андерсен
источник
1
Есть разница между комментированием и документированием.
Том Хотин - tackline
1
Совершенно верно. Именно поэтому я не комментирую геттеры и сеттеры. Они должны быть понятными, а добавление комментария указывает на то, что код не требует пояснений.
Thorbjørn Ravn Andersen,
0

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

АКФ
источник
Плохо - люди не читают полевые комментарии. Javadoc даже не создает личную документацию по умолчанию, а IDE не показывают вам документацию по полям, когда вы используете быструю справку по вызову метода.
Trejkaz
люди не читают комментарии к полям без необходимости. Если возникнет необходимость, чем больше информации, тем лучше.
akf
0

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

Алекс Б
источник
0

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

Поль Сонье
источник
Они говорят сами за себя, только если вы говорите «это средство задания свойств». В противном случае клиент API не имеет ни малейшего представления о том, что на самом деле происходит внутри методов
oxbow_lakes,
1
Кто сказал что-нибудь о самоочевидности?
Пол Сонье