Question

何时在方法开头使用块注释，何时使用javadoc样式的注释是否合适？

在Java style guide的“评论”部分，我发现了这一点：

Java程序可以有两种   评论：实施意见和   文件评论。履行   评论是在C ++中找到的，其中   由/*...*/和//分隔。   文档评论（称为“doc   评论“）仅限Java，而且是   由/**...*/分隔。医生评论   可以使用提取到HTML文件   javadoc工具。

实施意见适用于   评论代码或评论   关于具体实施。   文档评论旨在描述   代码的规范，来自   实施自由的观点。成为   由可能没有的开发人员阅读   必须有源代码   手。

因此，另一种表达我的问题的方法是：方法何时应该从无实现的角度（Javadoc）而不是关于特定实现的注释来获得代码规范，反之亦然？接口是否会获得javadoc注释，而实现会获得块注释？

编辑：根据迄今为止的答案，我认为我没有正确传达我的问题。

以下是我想知道的一个例子。

/**
 * Javadoc comment here about general implementation?
 */
/*
 * Should I now have a separate block comment for my specific implementation?
 */
public void foo()
{
...
}

两种不同的评论风格传达两种不同类型的信息。是否存在方法应该具有领先的javadoc注释和前导块注释的情况？

甚至要问的灵感是Eclipse刚刚为我自动生成了这个：

/*
 * (non-Javadoc)
 * @see my.package#process()
 */

我认为这里有某种样式，在我上面链接的评论规范中没有特别声明。

Answer 1

类的用户需要知道的信息应该进入Javadoc评论。

修改开发人员修改类的信息需要知道进入正常评论（块或行）。

当公开可见时，任何代码块（类，接口，字段，方法，构造函数，......）都可能两者一个Javadoc注释和一个普通注释块以及内部文件是必需的。

就个人而言，我倾向于写非常少的非Javadoc注释，因为我更喜欢以自我记录的方式构建我的代码。

Answer 2

在我看来，Javadoc评论是您写给使用您的代码的人以及调用您的方法的人的评论。

Javadoc注释更侧重于方法的参数，您的方法将返回的内容取决于您为方法提供的参数。

阻止评论是内部评论，您为维护代码的人撰写的评论。

块注释对于理解代码如何工作，工作原理以及用于执行实际工作的操作非常重要。

Answer 3

在我看来，将块注释置于方法的顶部是没有意义的（好吧，永远不要说永远，但至少在大多数情况下）。 Javadoc对接口方法的注释指定了契约，它们告诉实现的类方法，因此如果有多个类实现单个接口，用户可以决定使用哪个类。想想List界面;实现ArrayList和LinkedList适用于不同的用例，因此各自的文档可能会解释它们的优缺点。

我内联阻止关于非常具体的事情的评论。我希望实现特定的doc直接在实现的位置。当然你应该尽可能少地使用它们。使用富有表现力的变量和方法名称，它们会自动添加低级文档。

Eclipse自动生成的块注释供您填写，并可能通过添加缺少的星号来使它们成为Javadoc注释。我不确切地知道它们出现在哪种情况下，但是当你从现有类中提取接口时。然后，类中的Javadoc转到interface方法，类方法获取块注释。这背后的原因是，通常在实现接口时，您实际上并没有那么多要添加的东西。我再次使用List作为示例。 size()方法不需要ArrayList和LinkedList实施中的任何其他文档。它们没有任何价值可言。当然这个例子是设计的，因为实际的实现（至少是OpenJDK）做有Javadocs，但我认为没有必要，实际上不添加任何有价值的东西。更糟糕的是，它们提供的甚至比界面文档更少信息。

Javadoc评论与块评论？

3 个答案: