Javadoc注释与块注释？

什么时候适合在方法的开头使用块注释，什么时候适合使用javadoc样式的注释

从“评论”一节中，我发现：

Java程序可以有两种 意见：实施意见和建议 文件评论。实施 注释是在C++中发现的 由

/*…*/

和//分隔。 文档注释（称为“文档 注释”）仅为Java，并且 由

/**…*/

分隔。文档注释 可以使用 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()
 */

---

我发现这里有一些样式，在我上面链接的注释规范中没有特别声明。

在我看来，Javadoc注释是您写给使用您的代码和调用您的方法的人的注释

Javadoc注释更关注方法的参数，方法将返回什么取决于给方法的参数

块注释是内部注释，是您为维护代码的人员编写的注释

块注释对于理解代码如何工作、为什么工作以及用于实际工作的操作非常重要。

类用户需要知道的信息应该放在Javadoc注释中

修改类的开发人员需要知道的信息进入普通注释（块或行）

任何代码块（类、接口、字段、方法、构造函数等）都有可能同时具有Javadoc注释和普通注释块，而这两者都需要公开可见和内部文档

---

就我个人而言，我倾向于写很少的非Javadoc注释，因为我更喜欢以一种自我文档化的方式来构造代码。

在我看来，将块注释放在方法的顶部是没有意义的（好吧，永远不要说从不，但至少在大多数情况下是这样）。接口方法上的Javadoc注释指定了契约，类方法上的注释说明了实现，因此，如果有多个类实现单个接口，用户可以决定使用哪个类。考虑

列表

界面；实现

ArrayList

和

LinkedList

适用于不同的用例，因此它们各自的文档可能会解释它们的优缺点

我会阻止对非常具体的事情的评论。我希望实现特定的文档直接位于实现所在的位置。当然你应该尽量少用。使用表达性变量和方法名称，它们会自动添加低级文档

---

Eclipse自动生成的块注释供您填写，并可能通过添加缺少的星号使其成为Javadoc注释。我不知道它们具体出现在什么情况下，但有一种情况是从现有类中提取接口时。然后类中的Javadoc转到接口方法，类方法获得块注释。这背后的原因是，通常在实现接口时，您实际上没有太多要添加的内容。我再次以

List

为例。

size（）

方法在

ArrayList

和

LinkedList

实现中不需要更多文档。它们没有任何附加价值。当然，这个例子是人为设计的，因为实际的实现（至少是OpenJDK）确实有Javadocs，但我认为没有必要这样做，事实上，Javadoc并没有增加任何价值。更糟糕的是，它们提供的信息甚至比接口文档更少。

他们不是同一个人吗？@Coronatus:不是。我每天都读JDK和Apache Commons Javadoc，我不是这两个项目的维护人员。有时，他们是同一个人。但另一些时候，他们不是。以一个著名的Java库为例，比方说Hibernate。Javadoc注释是为在应用程序中使用Hibernate的人编写的。块注释是为开发Hibernate和阅读Hibernate源代码的人编写的。但是，这并不是对我问题的回答。谢谢。有没有不值得javadoc注释的方法？我可以想象一个实现接口的类，接口中的方法有一个javadoc。在我的实现中不使用javadoc合适吗？或者，最好的经验法则是始终提供javadoc注释和块注释（提供用户特定信息以及单独的程序员信息）？@hatorade：当我实现一个接口时，我通常在类级别只有一个javadoc注释。这应该可以解释这个实现的意义所在。接口定义的方法通常不需要进一步的文档，比如