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;
    }

基本上我想问一下，在评论中使用{@link}获取getter和setter方法是否正确？或者我应该使用正常评论而不使用{@link}？这种方式是不是java标准？

Answer 1

实际上，我故意不使用javadoc getter和setter，因为你没有通过这样做来增加任何价值 - 它们就是它们......存取方法。事实上，你会通过向它们添加javadoc来创建一种代码膨胀。

我只把javadoc放在非getter / setter上。

Answer 2

我建议为您的set / get方法生成独立文档，同时仍然使用{@link}，即两者兼而有之。这样，当字段可访问时，人们仍然可以访问其文档。如果之后由于重构而变得私有，那么你也不会最终得到一堆不完整的Javadoc，这些Javadoc也需要修改。
虽然setter / getter方法的文档可能看起来像代码膨胀，但我仍然建议创建它有几个原因：
- 它为您提供了一个标准位置来提及重要信息，例如不应该是null的setter参数或者在特定接口实现中效率低下的getter。
- 它不会假设读者自动知道支持字段的作用。当然，setLength()在某些情况下可能具有足够的描述性，但setLimit()究竟做了什么？
- 它不假设是支持字段，或者get / set方法只是在特定实现中执行。令人遗憾的是，当重构受到兼容性问题的限制时，会遗留各种工件。例如。 setLimit()可以委托给setSizeLimit()，这是应该注意的事项。
- 它消除了所有歧义。你认为是常识的可能对所有人来说都不是直截了当的。如果没有文件，将会做出各种假设，这些假设可能是也可能不是。例如，在列表实现中，setLength(0)是否也将所有包含的引用设置为null？
- 最重要的是，它允许Javadoc政策归结为简单的“记录所有地方的所有内容”。另一方面，制定一项有各种例外的政策，将不可避免地导致松懈和最终没有文件记录的代码。

Answer 3

约定的事项。使组织与组织不同。以前，只要显而易见，我们就会被要求不要对getter和setter进行评论。这与没有{@link}的评论相同。

目前，我们添加{@link}，因为之前编写的代码已经具有此约定。

Answer 4

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

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

至于你的文档：它没有增加方法名称已经建议的新内容。所以我会删除它，或者添加一些关于autoKey确实做什么的额外文档（我从代码片段中不清楚），是否可以设置为null，.... / p>

Answer 5

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

Answer 6

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

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

所有这些都是为了说明它们不需要记录。

<块引用>

当然，如果在您的应用程序上下文中，您在>setter 中添加了特定指令，例如，与您的需求和程序逻辑相关，在我的>意见中，没有什么可以阻止您添加描述性注释顺其自然

getter和setter方法的Java注释

6 个答案: