Прості коментарі 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) зарплату працівника. Це просто здається таким зайвим. Тепер я міг побачити щось складніше, що ви можете написати більше в (а) частинах, щоб надати контексту, але для більшості учасників / сеттерів формулювання майже точно таке.

Мені просто цікаво, якщо для простих гетерів / сеттерів нормально заповнити лише (а) частину АБО (б) частину.

Що ти думаєш?

Зазвичай я просто заповнюю парам-частину для сетерів, а частину @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 () "задає гобблдигук", я хочу когось задушити.

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

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

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

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

Якщо в getter / setter немає спеціальної операції, я зазвичай пишу:

З Javadoc (з приватною опцією):

/** Set {@see #salary}. @param {@link #salary}. */
public void setSalary(float salary);

та / або

/** 
 * Get {@see #salary}.
 * @return {@link #salary}.
 */
public float salary();

За допомогою Доксигену (з приватним екстрактом):

/** @param[in] #salary. */
public void setSalary(float salary);

/** @return #salary. */
public float salary();

Коментувати аксесуарів, особливо якщо вони ніде не роблять жодних операцій, є непотрібним і марним шляхом.

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

Якщо, з іншого боку, ваше person.getFirstName()не поверне прізвище людини ... ну, не давайте туди, чи не так?

Нічого не вкладайте, якщо назва поля вміщує опис вмісту.

Як правило, нехай код стоїть самостійно, і уникайте коментування, якщо це можливо. Це може зажадати рефакторингу.

РЕДАКТИРУВАННЯ: Вищезазначене стосується лише геттерів та сетер. Я вважаю, що все, що не є тривіальним, має бути належним чином javadoc'ed.

нормально заповнити (б) частину, особливо якщо ви помітили коментар до декларації поля із зазначенням того, що це поле.

Якщо javadoc нічого не додає, я видаляю javadoc і використовую автоматично створені коментарі.

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