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议忽略作者的信息。
