Javadoc @author 标签的良好实践

Question

我想知道创建 Javadoc 时的最佳实践。我有一个包含很多文件的项目。许多开发人员已经创建了代码。每个文件都有一个注释 @author ，所以很明显是谁创建了一个特定的类。

但是当其他一些开发人员向文件添加新代码、修改它等时，他应该如何通知团队的其他成员他已经创建了一些新功能或已经修改了现有代码？换句话说，我们应该如何“让 Javadocs 与现实兼容”？ ;)

• 将他的名字添加到现有的 @author 标签？然后，如果有任何疑问，就更容易确定该问谁。
• 为每个新方法、内部类等添加一个 @author 标签？

当然，由于我们使用 SVN，很容易调查谁做了什么，但是为了保持清晰，还应该考虑这些 Javadoc 内容。

使用这些 @author 标签的最佳方式是什么？

原文由 radekEm 发布，翻译遵循 CC BY-SA 4.0 许可协议

Answer 1

我会说对于大多数目的 @author 是不需要的噪音。 API 的用户不应该——也可能不会——关心或想知道谁编写了哪些部分。

而且，正如您已经指出的那样，SVN 已经以比代码更权威的方式保存了这些信息。所以如果我是团队中的一员，我总是更喜欢 SVN 的日志并忽略 @author 。我敢打赌，无论您采用何种政策，代码都会与现实不同步。遵循“不要重复自己”原则，为什么要将此信息保存在两个地方？

但是，如果出于某些官僚或政策原因必须将此信息包含在代码中，您是否考虑过在签入时自动更新代码中的 @author 标签？您 可能 可以使用 SVN 挂钩实现此目的。例如，您可以按照更改文件的顺序列出所有更改给定文件的开发人员；或者谁改变最多；管他呢。或者，如果 @author 在您向外界发布的（源）代码中被强制要求，您可以考虑添加 @author 自动作为发布版本的一部分（我怀疑您可以获得此信息以某种方式从 SVN 中获取）。

至于添加不止一个类级别 @author 标签（或其他评论），我会说你会积累很多无用的噪音。 （同样，你有 SVN。）

根据我的经验，识别历史变更（比如对一行代码或方法的变更），然后计算出这与哪个变更集相关（以及哪个轨道票）更有用。然后你就有了变更的完整上下文：你有工单，变更集，你可以在同一张工单上找到其他变更集，或者大约在同一时间，你可以找到相关的工单，你可以看到所有的变更形成了那个工作单元。你永远不会从代码中的注释或注释中得到它。

原文由 Paul 发布，翻译遵循 CC BY-SA 3.0 许可协议

Answer 2

您可能需要考虑 为什么 要在源代码中添加作者标签。 Apache 基金会没有，我同意。

https://web.archive.org/web/20150226035235/www.theinquirer.net/inquirer/news/1037207/apache-enforces-the-removal-of-author-tags

据我所知，这是一种从源代码打印在纸上开始的货物崇拜方式。使用现代版本控制系统，无论如何都可以在历史中找到这些信息和更多信息。

原文由 Thorbjørn Ravn Andersen 发布，翻译遵循 CC BY-SA 4.0 许可协议