Javadoc 注释与阻止注释?

2022-09-01 02:59:37

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

Java风格指南的“注释”部分,我发现了这个:

Java 程序可以有两种类型的注释:实现注释和文档注释。实现注释是在 C++ 中找到的注释,它们由 和 // 分隔。文档注释(称为“文档注释”)仅支持 Java,由 分隔。可以使用javadoc工具将文档注释提取到HTML文件中。/*...*//**...*/

实现注释用于注释掉代码或有关特定实现的注释。Doc 注释旨在从无实现的角度描述代码的规范。由开发人员阅读,他们可能不一定拥有源代码。

因此,另一种表达我问题的方法是:从无实现的角度来看,方法何时值得规范代码(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()
 */

而且我认为这里发生了某种样式,这些样式在我链接到上面的注释规范中没有明确声明。


答案 1

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

修改类的开发人员需要知道的信息将进入普通注释(块或行)。

而且,当需要公开可见和内部文献时,任何代码块(类,接口,字段,方法,构造函数等)都可能同时具有Javadoc注释和普通注释块。

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


答案 2

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

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

阻止注释是内部注释,是您为维护代码的人员编写的注释。

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


推荐