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

Question

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

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

Что ты думаешь?

Answer 1

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

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

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

Answer 2

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

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

Answer 3

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

Answer 4

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

Answer 5

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