Простые комментарии Getter/Setter
https://stackoverflow.com/questions/1028967
italiano
english
français
española
中国
日本の
العربية
Deutsch
한국어
Português
RussianВопрос
Какое соглашение вы используете для комментирования геттеров и сеттеров?Вот что я задавался вопросом в течение довольно долгого времени, например:
/**
* (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), чтобы дать контекст, но для большинства геттеров/сеттеров формулировка почти одинакова.
Мне просто любопытно, можно ли для простых геттеров/сеттеров заполнять только часть (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 () " устанавливает gobbledygook. & Quot ;, я хочу кого-то задушить.
Вообще ничего, если я могу помочь. Методы получения и установки должны быть самоочевидными.
Я знаю, что это звучит как отсутствие ответа, но я стараюсь использовать свое время для комментирования вещей, требующих объяснения.
Я бы сказал, что беспокоиться только о том, чтобы комментировать методы получения и установки, если они имеют какой-то побочный эффект или требуют какого-либо предварительного условия вне инициализации (то есть: получение удалит элемент из структуры данных или для установки что-то, что вам нужно, чтобы сначала были х и у). В противном случае комментарии здесь довольно излишни.
Редактировать: Кроме того, если вы обнаружите, что в вашем методе получения / установки есть много побочных эффектов, вы можете захотеть изменить метод получения / установки на другое имя метода (то есть: 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 () не возвращает имя человека ... ну, давайте не будем идти туда, не так ли?
Не помещайте ничего, если имя поля достаточно описательно для содержимого.
Как правило, позвольте коду быть самостоятельным и избегайте комментариев, если это вообще возможно. Это может потребовать рефакторинга.
РЕДАКТИРОВАТЬ: Вышесказанное относится только к геттерам и сеттерам. Я считаю, что все, что нетривиально, должно быть правильно написано.
заполнить часть (b) можно, особенно если вы добавите комментарий к объявлению поля, указывающий, что это за поле.
Если javadoc ничего не добавляет, я удаляю javadoc и использую автоматически сгенерированные комментарии.
Я всегда заполняю оба. Дополнительное время, затрачиваемое на набор текста, незначительно, и в целом больше информации лучше, чем меньше.
Если это геттер / сеттер, это должно быть задокументировано.
Я отступаю здесь, но если это можно сделать свойством, возможно, это лучше для более простого кодирования пользователей класса. Я отступлю дальше, но что касается всех комментариев, в которых есть "java" кто-нибудь из них сказал, что это Java? (теги, но вопрос может действительно применяться где угодно)
