Javadoc@Author好的用法?

内容来源于 Stack Overflow,并遵循CC BY-SA 3.0许可协议进行翻译与使用

  • 回答 (2)
  • 关注 (0)
  • 查看 (57)

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

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

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

当然,因为我们使用SVN,所以很容易调查谁做了什么,但为了保持清晰,这个Javadoc的东西也应该被考虑到。

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

提问于
用户回答回答于

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

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

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

至于添加不止一个类级别@author标签(或其他评论),我会说你会累积很多无用的噪音。(再次,你有SVN。)

根据我的经验,识别历史变化(比如更改一行代码或一种方法),然后确定涉及哪个变更(以及哪个轨道标签)更有用。然后,您可以获得更改的完整上下文:您拥有票证,更改集,可以在同一张票上找到其他更改集,或者在同一时间找到相关票证,并且可以查看所有更改形成了这个工作单位。你永远不会从代码中的注释或注释中获得这个。

用户回答回答于

您可能需要考虑为什么您需要源代码中的作者标签。Apache基金会不这样做,我同意。

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

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

扫码关注云+社区

领取腾讯云代金券