Javadoc @author 标记良好实践

java javadoc author

2022-08-31 13:48:42

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

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

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

当然，由于我们使用SVN，因此很容易调查谁做了什么，但是为了保持清晰，也应该考虑Javadoc的东西。

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

答案 1

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

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

但是，如果出于某种官僚主义或政策原因，必须将此信息包含在代码中，您是否考虑过在签入时自动更新代码中的标记？你可以用一个SVN钩子来实现这一点。例如，您可以按照更改给定文件的顺序列出所有更改给定文件的开发人员;或者谁改变了它;或者别的什么。或者，如果在您向外界发布的（源代码）代码中强制要求，则可以考虑自动添加作为发布版本的一部分（我怀疑您可以以某种方式从SVN中获取此信息）。@author@author@author

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

根据我的经验，识别历史更改（例如对一行代码或方法的更改）然后确定这与哪个更改集相关（以及哪个跟踪票证）更有用。然后你有了更改的完整上下文：你有票证，更改集，你可以在同一票证上找到其他更改集，或者大约在同一时间，你可以找到相关的票证，你可以看到形成该工作单元的所有更改。你永远不会从代码中的注释或注释中得到这个。

答案 2

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

http://www.theinquirer.net/inquirer/news/1037207/apache-enforces-the-removal-of-author-tags

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