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

Я могу подтвердить, что это Xcode 6, связанный не с iOS 8.

У меня есть две машины разработки. На одном из них у меня есть Xcode 5. Я работал все время на этой машине, и мой URL был в порядке (фотоприложение, фотографии видны).

Вчера я проверил в форме git мой источник на машине с Xcode 6. Я заметил, что мои фотографии больше не видны, только фотографии, созданные во время этого сеанса приложения.

После небольшой отладки я понял, что файл: /// var / mobile / Applications / B6A6BAEF-C90C-4A2A-93DB-E6700B88971F / Документы / меняются при каждом запуске приложения.

Все это время я работаю с устройством iOS 7.

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

118
задан ThaDon 24 August 2013 в 01:55
поделиться

12 ответов

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

80
ответ дан 24 November 2019 в 01:45
поделиться

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

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

0
ответ дан 5 October 2019 в 23:26
поделиться

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

0
ответ дан 24 November 2019 в 01:45
поделиться

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

0
ответ дан 24 November 2019 в 01:45
поделиться

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

0
ответ дан 24 November 2019 в 01:45
поделиться

Don't put anything if the field name is suficiently descriptive of the contents.

Generally, let the code be self standing, and avoid commenting if at all possible. This may require refactoring.

EDIT: The above refers to getters and setters only. I believe anything non trivial should be properly javadoc'ed.

1
ответ дан 24 November 2019 в 01:45
поделиться

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

В вашем случае:

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

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

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

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

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

12
ответ дан 24 November 2019 в 01:45
поделиться

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

Edit: Кроме того,

34
ответ дан 24 November 2019 в 01:45
поделиться

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

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

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

1
ответ дан 24 November 2019 в 01:45
поделиться

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

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

36
ответ дан 24 November 2019 в 01:45
поделиться

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

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

172
ответ дан 24 November 2019 в 01:45
поделиться

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

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

Я уверен, что я »

4
ответ дан 24 November 2019 в 01:45
поделиться
Другие вопросы по тегам:

Похожие вопросы: