4

我的问题是我应该评论如下：

/**
     * 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标准？

4

6 回答 6

9

实际上，我故意不使用 javadoc getter 和 setter，因为这样做并没有增加任何价值——它们就是它们......访问器方法。实际上，通过将 javadoc 添加到它们，您将创建一种代码膨胀。

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

于 2012-04-06T06:37:20.167 回答
1

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

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

    • 它为您提供了一个标准位置来提及重要信息，例如不应该使用的 setter 参数null或在接口的特定实现中效率极低的 getter。

    • 它不假定读者自动知道支持字段的作用。当然，setLength()在某些情况下可能具有足够的描述性，但究竟是setLimit()做什么的呢？

    • 它不假设有一个支持字段，或者 get/set 方法仅在特定实现中这样做。不幸的现实是，当重构受到兼容性问题的限制时，会留下各种工件。例如setLimit()可以委托给setSizeLimit()，这是应该注意的。

    • 它消除了所有的歧义。你认为的常识可能对所有人来说都不是直截了当的。如果没有文档，将做出可能正确或不正确的各种假设。例如，在列表实现中，是否setLength(0)还设置所有包含的引用null？

    • 最重要的是，它允许 Javadoc 策略归结为一个简单的“随处记录所有内容”。另一方面，拥有各种例外情况的政策将不可避免地导致松懈和最终未记录的代码。

于 2012-04-06T06:50:09.523 回答
0

约定事项。因组织而异。以前，我们被要求不要打扰评论 getter 和 setter，只要它的作用很明显。这与没有{@link}.

目前，我们添加{@link}之前编写的代码已经有这个约定。

于 2012-04-06T06:37:14.457 回答
0

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

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

至于您的文档：它没有为方法名称已经暗示的内容添加任何新内容。所以我会删除它，或者添加一些关于autoKey确切作用的额外文档（从片段中我不清楚），它是否可以设置为null, ... 。

于 2012-04-06T06:38:34.753 回答
0

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

于 2012-04-06T06:55:33.253 回答
0

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

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

所有这一切都表明它们不需要记录在案。

当然，如果在您的应用程序的上下文中，您在 >your setter 中添加特定指令，例如，根据您的需求和程序的逻辑，在我看来，没有什么能阻止您向它添加描述性注释行

于 2021-02-01T16:51:58.570 回答