Javadoc @author标签的良好做法

创buildJavadoc时,我想知道最佳做法。 我有一个项目与许多文件。 代码已经由许多开发人员创build。 每个文件都有注解@author ,所以很明显是谁创build了一个特定的类。

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

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

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

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

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

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

    但是,如果有一些官方的或政策的原因,这些信息必须包含在代码中,你是否考虑过在代码中自动更新代码中的@author标签? 你可以用SVN钩子来实现这个。 例如,你可以列出所有改变给定文件的开发人员。 或谁改变了最多; pipe他呢。 或者,如果@author是在你发布到外部世界的(源代码)代码中被强制的,你可以考虑自动添加@author作为发布版本的一部分(我怀疑你可以以某种方式从SVN中获取这些信息)。

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

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

    你可能想考虑为什么你想在源代码中的作者标签。 Apache基金会不,我同意。

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

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

    你可以有多个@author标签。 如果你对一个类做了一些大的修改,只需要在其中添加一个新的@author标签。 您不需要标记所做的更改或将您的姓名放在更改上,因为修订历史应该能够清楚地显示。

    在有很多开发人员的大型和长时间运行的项目中,了解ho是否对给定的代码负责,谁可以为您提供额外的信息等是非常有用的。 在这种情况下,使用@author标签可以在文件中获得这样的信息。 不标记谁创build了该文件或谁做出了重大贡献,但谁是该代码的联系人。 那些可能是非常不同的人,原来的作者可能已经在不同的项目上,或者几年前离开了公司。

    我认为这个庞大的项目可能会很方便,但是有一个警告。 保持每个文件的作者信息是非常困难的,因为文件数量巨大,迟早会失败。 越来越多的文件将有过时的信息,开发人员将不再信任这个@author作为信息源,而只是忽略它。

    可能工作的解决scheme不是在每个文件上保留@author,而仅在每个模块上保留@author(高级包)。 Javadoc有一个function,在这里你不仅可以logging文件,而且可以logging整个软件包( 更多细节见这个问题 )。

    然而,这是一个特例,只要你的项目不是那么大,我build议忽略作者的信息。