Какое соглашение вы используете для комментирования геттеров и сеттеров? Вот то, что я задумывался довольно давно, например:
/**
* (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 для геттеров:
Таким образом, инструменты проверки javadoc (такие как предупреждения Eclipse) будут чистыми и не будут дублироваться.
источник
Абсолютно бессмысленно - вам лучше без такого рода дерьма, загромождающего ваш код:
Очень полезно при наличии гарантии:
В частности, объяснение того, что на самом деле означает свойство, может иметь решающее значение в моделях предметной области. Всякий раз, когда я вижу боб, полный свойств с непонятными названиями, понятными только инвестиционным банкирам, биохимикам или квантовым физикам, и в комментариях объясняется, что метод setGobbledygook () «настраивает чепуху», я хочу кого-нибудь задушить.
источник
В общем, ничего, если я могу помочь. Геттеры и сеттеры не требуют пояснений.
Я знаю, что это звучит как отказ от ответа, но я стараюсь использовать свое время, чтобы комментировать вещи, требующие объяснения.
источник
Я бы сказал, что беспокоиться о комментировании геттеров и сеттеров можно только в том случае, если у них есть какой-то побочный эффект или требуется какое-то предварительное условие вне инициализации (например: получение удалит элемент из структуры данных или для того, чтобы установить что-то, что вам нужно чтобы сначала были на месте x и y). В противном случае комментарии здесь излишни.
Изменить: Кроме того, если вы обнаружите, что в вашем геттере / сеттере задействовано много побочных эффектов, вы можете изменить геттер / сеттер, чтобы иметь другое имя метода (например, push и pop для стека) [Спасибо за комментарии ниже]
источник
Спросите себя, что вы хотите, чтобы люди видели, когда комментарии просматриваются как документы JavaDocs (из браузера). Многие говорят, что документация не нужна, потому что это очевидно. Этого не будет, если поле является частным (если вы явно не включите JavaDocs для частных полей).
В твоем случае:
Непонятно, в какой зарплате выражается. Это центы, доллары, фунты, юань?
При документировании сеттеров / геттеров я предпочитаю отделять что от кодировки. Пример:
Первая строка говорит, что возвращает высоту. В возвращаемом параметре указывается высота в метрах.
источник
public void setSalary(float aud)
(или более реалистичноpublic void setSalary(BigDecimal aud)
). Еще лучше, свойство должно быть типаabstract class CurrencyAmount
, которое, в свою очередь, имеет свойстваjava.util.Currency currency
иjava.math.BigDecimal amount
. Большинство разработчиков, с которыми я работал, ужасно ленивы с JavaDoc, но применение подобного API делает это менее проблематичным.Почему бы им просто не включить тег ссылки, чтобы вы могли комментировать значение поля и ссылку из геттеров и сеттеров.
Так что документация применима к методам получения и установки, а также к полю (если включены частные javadocs).
источник
Такого рода шаблонов можно избежать, используя Project Lombok . Просто задокументируйте переменную поля, даже если она
private
, и позвольте аннотациям Lombok генерировать правильно задокументированные методы получения и установки.Для меня одно только это преимущество стоит затрат .
источник
Я действительно разочарован ответами, в основном утверждающими, что полное документирование - пустая трата времени. Каким образом клиенты вашего API должны знать, что вызываемый метод
setX
является стандартным установщиком свойств JavaBean, если вы не указали это четко в документации ?Без документации вызывающий абонент вообще не знал бы, имел ли метод какие-либо побочные эффекты, кроме скрещивания пальцев по поводу очевидного соблюдения соглашения.
Я уверен, что я не единственный здесь, кто имел несчастье узнать на собственном опыте, что вызываемый метод
setX
делает гораздо больше, чем просто устанавливает свойство.источник
setX
имели побочные эффекты, отличные от ожидаемых, я действительно могу с уверенностью сказать, что это не идеальный мир.Если в геттере / сеттере нет специальной операции, я обычно пишу:
С помощью Javadoc (с частным вариантом):
и / или
С Doxygen (с опцией частного извлечения):
источник
{@see #salary}
недействителен в сгенерированной документации.Комментирование аксессуаров, особенно если они нигде не выполняют никаких операций, не нужно и бесполезно.
Если кто-то, читающий ваш код, не может этого понять
person.getFirstName()
возвращает имя человека, вы должны попробовать все, что в ваших силах, чтобы его уволили. Если он творит чудеса с базой данных, бросает несколько кубиков, вызывает секретаря по именам, чтобы узнать имя, можно с уверенностью предположить, что это нетривиальная операция, и хорошо ее задокументировать.Если же, с другой стороны, вы
person.getFirstName()
не укажете имя человека ... ну, не будем ли туда идти?источник
Ничего не указывайте, если имя поля в достаточной мере описывает содержимое.
В общем, пусть код будет самодостаточным, и по возможности избегайте комментариев. Это может потребовать рефакторинга.
РЕДАКТИРОВАТЬ: Вышеупомянутое относится только к геттерам и сеттерам. Я считаю, что все нетривиальное нужно должным образом оформить с помощью javadoc.
источник
можно заполнить часть (b), особенно если вы добавите комментарий к объявлению поля, указывающий, что это за поле.
источник
Если javadoc ничего не добавляет, я удаляю javadoc и использую автоматически сгенерированные комментарии.
источник
Я всегда заполняю и то, и другое. Дополнительное время, затрачиваемое на набор текста, ничтожно, и в целом больше информации лучше, чем меньше.
источник