Javadoc @author标签的良好做法

Question

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

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

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

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

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

Answer 1

我想说，对于大多数用途来说，@author是不需要的噪音。API的用户不应该-也许不应该-关心或想知道谁编写了哪些部分。

而且，正如您已经说过的那样，SVN已经以比代码更权威的方式拥有此信息。因此，如果我是团队中的一员，我将始终喜欢SVN的日志，而忽略@author。我敢打赌，无论您采用哪种策略，代码都将与现实不同步。遵循“不要重复自己”的原则，为什么将这些信息放在两个地方？

但是，如果出于官僚或政策原因必须将此信息包含在代码中，那么您是否考虑过在@author签入时自动更新代码中的标签？你可以 或许
与SVN钩子实现这一目标。例如，您可以列出所有更改给定文件顺序的开发人员；或更改最多的人；管他呢。或者，如果@author您在外部发布的（源）代码中强制执行，则可以考虑将@author自动添加作为发布版本的一部分（我怀疑您可以某种方式从SVN中获取此信息）。

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

以我的经验，识别历史更改（例如对一行代码或方法的更改），然后找出与之相关的更改集（以及哪个跟踪记录），会更加有用。然后，您具有更改的完整上下文：您拥有故障单，更改集，可以在同一故障单上找到其他更改集，或者大约在同一时间可以找到相关的故障单，并且可以看到所有更改形成了那个工作单元。您永远不会从代码中的注释或注释中获得此信息。