getter 或 setter Javadoc 是否应提及默认值？

Question

记录可选属性的默认值的约定是什么？

当 class 包含带有 getter 和 setter 方法的可选属性时，默认值是否应由 getter 或setter 方法？还是两者都有？

当用户停下来问自己"wait... what happens if I don't set this value?"他们会先看哪个方法？

这是一个具体的例子：

public interface JsonLoader
{
  /**
   * @param verify true if the returned JSON should be verified
   */
  void setVerify(boolean verify);

  /**
   * @return true if the returned JSON should be verified
   */
  boolean getVerify();

  /**
   * Loads the JSON file.
   * @throws VerificationException if the JSON was invalid
   */
  String load() throws VerificationException;
}

在上面的代码中，我应该在哪里指定 "verify" 默认为真？

Answer 1

Builder 模式通常没有 getter（导致流畅 API），因为其想法是设置所需的值并构建结果对象。

甚至 you 链接的维基百科示例也没有吸气剂。

否则，没有 specified 地方有默认值，所以我建议查看其他 API 看看他们做了什么选择，选择让您满意的东西。

这根本不重要，只要它在 Javadoc 中某处有记录即可。如果您的位置正确 class，即使它可能不在您想象的第一位，您也会找到它。毕竟 javadoc 并没有那么大。

在您的示例代码中，I 期望默认值为 false 如果没有另外说明，但如果不是（或者即使是）它至少会在 setter 中被提及。但同样，没有规则，你会看到各种各样的习俗。

Answer 2

没有规定 class 需要 getter 和 setter。但是，class 的基本思想是从中创建对象。 class 就像一个蓝图。该对象是您使用蓝图构建的对象。该对象需要具有一些属性。如果 class 没有 setter 方法，则无法使用您正在构建的对象。同样，如果您需要使用该对象的属性，则需要一个 getter。你可能不需要他们中的任何一个，但不需要他们两个。

Answer 3

如果您谈论的是 getter 和 setter，那么您不是在讨论构造。我期待某种构造函数，将您的对象初始化为有效状态。那应该处理它，并且应该将文档放在那里。可能有多个构造函数。

如果您使用构建器模式，则应将其添加到 build() 或 construct() 方法中，因为它应该验证并创建所需的对象。

如果你有一个 DTO，那么它应该有一个构造函数，或一个生成器。 getters 和 setters 通常不是正确的设计。

但是，如果您想这样做，我会添加具有默认值的 getter，并这样称呼它们，即 getBananaWithDefault()，或者getDefaultedBanana()，并且不公开普通的 getter（或者让 getter 也有不同的名称）

在接口示例中，我将记录如下：

/**
 * if the returned JSON should be verified
 */
void setVerify(boolean setVerifying);

/**
 * @return whether the JSON should be verified
 */
boolean getVerify();

/**
 * Loads the JSON file.
 * Will default to use verification if not set
 * @throws VerificationException if verification is enabled and the JSON is invalid
 */
String load() throws VerificationException;

但这是我个人的看法。我什至可能会放弃 setVerify 和 getVerify 而只有一个 disableVerification() 方法

getter 或 setter Javadoc 是否应提及默认值？

Should default values be mentioned by the getter or setter Javadoc?

java

javadoc