Java getter和setter方法的注释

Question

我的问题是，我应该像下面这样评论吗：

/**
     * Getter for {@link #auto_key}
     * @return {@link #auto_key}
     */
    public String getAuto_key() {
        return auto_key;
    }
    /**
     * Setter for {@link #auto_key}
     * @param auto_key the {@link #auto_key} to set
     */
    public void setAuto_key(String auto_key) {
        this.auto_key = auto_key;
    }

我想问一下，在getter和setter方法的注释中使用{@link}是否正确？还是应该使用不带{@link}的普通注释？这种写法是否符合Java标准？

- pd27

Answer 1

实际上，我故意不对getter和setter进行javadoc注释，因为这样做并没有增加任何价值-它们只是访问方法。事实上，通过为它们添加javadoc，您会创建一种代码膨胀。

我只在非getter/setter上放置javadoc注释。

- Bohemian

---

@eric 我认为，如果您需要记录一个字段是什么，那么您没有给它命名得足够好。getter返回的内容应该是完全明显的。使用Lombok（您肯定会用）不允许在访问器上使用任何javadoc，这意味着您必须给字段命名得很好。 - Bohemian

@eric 你所说的“为什么”是什么意思？设置器没有“为什么”，你只是将一个值分配给一个字段。例如，调用customer.setName("John Smith"); 的“为什么”是“我想将客户的姓名设置为John Smith”。如果您在暗示记录将字段设置为特定值的效果，例如car.setCruiseControlKph(100)，那么字段的名称应告诉您将其设置为特定值的效果。如果您想向值添加含义，请使用具有良好命名的枚举或参数对象。我坚信访问器永远不需要javadoc。 - Bohemian

是的，类似于 car.setCruiseControlKph(100) 这样的东西。我们处理相对复杂的建筑和能源系统模拟模型。单位可能比仅仅是 "km/h" 长很多，因此我希望在文档中写出它们，而不是在每个字段后面添加它们。我也想在需要时添加论文引用。对于枚举类型，即使它们有明确的名称，指定为什么应该优先选择其中一个也可能是值得的（例如，一个更快，另一个更准确但可能需要运行一整晚）。我同意记录每个 setter 方法可能会产生噪音。 - Eric Duminil

@eric 考虑在 getter 上使用注解（如果使用 lombok，则使用字段）。 - Bohemian

几周后：我们正在使用资源包和属性文件来存储字段，这些字段将用于GUI工具提示和PDF文档中。感谢有趣的讨论。 - Eric Duminil

Answer 2

我建议为您的set/get方法生成独立文档，同时仍使用{@link}，即做两者。这样，当字段可访问时，人们仍然可以访问其文档。如果之后由于重构而变为私有，则不会出现一堆需要修改的不完整Javadocs。

尽管setter/getter方法的文档可能看起来像是代码膨胀，但我仍建议出于以下几个原因创建文档：

- 它为您提供了一个标准位置来提及重要信息，例如不应为null的setter参数或特定接口实现中效率极低的getter。 - 它不会假设读者自动知道支持字段的作用。当然，在某些情况下，“setLength()”可能已经足够描述清楚了，但是“setLimit()”到底是做什么的呢？ - 它不会假设有一个支持字段，或者在特定实现中，get/set方法只是在做这件事。不幸的是，重构受兼容性问题的限制时，留下了各种各样的工件。例如，“setLimit()”可以委托给“setSizeLimit()”，这是应该注意的事情。 - 它消除了所有的歧义。您认为是常识的东西对其他人来说可能并不直观。没有文档，将会做出各种可能正确也可能不正确的假设。例如，在列表实现中，“setLength(0)”是否同时将所有包含的引用设置为null？ - 最重要的是，它使Javadoc策略简化为一个简单的“在任何地方都要记录所有内容”。另一方面，有各种例外的策略最终将导致放任不管和未记录文档的代码。

- thkala

Answer 3

访问器和修改器是类中的通用方法，其中应用了封装的概念（即具有私有实例属性）。这就是为什么在某些 IDE 中（例如 Netbeans），它们甚至可以自动生成。

此外，根据惯例，它们的名称非常明确地说明了它们的作用，因此可以将它们与其他更特定于业务需求的方法区分开来。

所有这些都表明它们不需要被文档化。

当然，如果在您的应用程序上下文中，例如在您的 setter 中添加了特定指令，以满足您的需求和程序逻辑，那么我认为，没有任何阻止您添加描述性注释行的。

- Mk21

Answer 4

惯例问题。因组织而异。以前，我们被要求不要在getter和setter上添加注释，只要它的作用很明显。这与没有{@link}的注释相同。

目前，我们添加{@link}，因为之前编写的代码已经遵循了这个惯例。

- Nishant

Answer 5

如果您在文档中使用{@link}引用#auto_key，那么这个变量就是公共可访问的（否则，在javadoc中链接将无法解析）。这意味着getter和setter是多余的。

我强烈建议将您的auto_key字段设置为私有，并保留getter和setter。然后调整getter和setter的名称以符合Java约定（autoKey，setAutoKey，getAutoKey）。并且考虑在更改autoKey时触发PropertyChangeEvent（因为getter/setter组合通常会建议这样做-请参见JavaBeans）。

至于您的文档：它没有为方法名称已经暗示的内容添加任何新内容。因此，我建议删除它，或者添加一些关于autoKey的额外文档，以说明它到底是什么（从片段中不清楚），是否可以设置为null等。

- Robin

Answer 6

除非方法看起来像一个getter或setter，但封装了不同的行为，否则不应该放置任何描述getter或setter的注释。

- ahanin