Javadoc @author标签的良好做法

2019年2月20日 21点热度 0条评论

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

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

  • 将他的名字添加到现有的@author标签中吗?然后,如果有任何疑问,更容易确定向谁询问。
  • 向每个新方法,内部类等添加@author标记吗?
  • 当然,由于我们使用SVN,因此很容易调查谁做了什么,但是为了保持清晰,也应该考虑这些Javadoc内容。

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

    解决方案如下:

    我会说,对于大多数目的@author是有害的噪声。 API的用户不应该-也许不应该-关心或想知道谁编写了哪些部分。

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

    但是,如果出于官僚或政策原因必须将此信息包括在代码中,那么您是否考虑过在 checkin 代码中自动更新@author标记?您可能可以通过SVN挂钩实现此目的。例如,您可以列出所有更改给定文件顺序的开发人员;或更改最多的人;管他呢。或者,如果在发布到外部的(源)代码中强制要求@author,则可以考虑将@author作为发布版本的一部分自动添加(我怀疑您可以某种方式从SVN中获取此信息)。

    至于添加多个类级别的@author标记(或其他注释),我会说您会积累很多无用的噪音。 (同样,您有SVN。)

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