我们在方法声明之上放置的文档的正确术语是什么？

Question

我正在写一篇白皮书，并且意识到我不确定我们在定义声明之前将哪些内部文档作为注释块使用的官方术语。

最终成为JavaDoc成员文档的相同事物。

这不仅仅是内部文件，我不确定“头文件”是一个好的术语。

请注意，我在寻找一个通用术语，而不是一个具体的特定语言（例如，Java/Perl的）

Answer 1

这被称为方法规范或规程。也就是说，它指定了过程的行为而不是实现细节。一些教科书将其称为该方法的合同，但这可能有点模糊。

Answer 2

它通常专业被称为“要求的条款”，或“保险条款”。

Answer 3

在我的组织中，我们称之为方法或功能doc评论。功能级文档可能是更广泛使用的术语。

Answer 4

我总是将它称为方法（或函数）注释，以区分它与类或文件注释。

Answer 5

我把它称为代码注释，就像那样简单。

Answer 6

我通常将其称为“内联文档”。对我来说就是这样 - 事实上，你的文档是，你的源代码是，所以文档将会更多地与代码保持同步。

（这是不能保证的，当然，但它确实鼓励程序员吃的蔬菜。这意味着开发人员可以在同一时间和在同一个地方改变文档行为的变化，而不是事后在另一个地方。）