我想知道创建Javadoc时的最佳实践。我有一个包含许多文件的项目。代码已由许多开发人员创建。每个文件都有一个注释@author，因此很明显谁创建了一个特定的类。
但是当其他开发人员为文件添加新代码，修改它等等时，他应该如何通知团队的其他成员他已创建了一些新功能或修改了现有代码？换句话说，我们应该如何“让Javadocs与现实保持一致”？ ;）
@author代码中？然后，如果有任何疑问，更容易确定要询问的人。@author标记？当然，由于我们使用SVN，很容易调查谁做了什么，但为了保持清楚，这个Javadoc的东西也应该被考虑在内。
使用这些@author代码的最佳方式是什么？
答案 0 :(得分：58)
我会说，在大多数情况下@author是不受欢迎的噪音。您的API的用户不应该 - 也可能不 - 关心或想知道谁编写了哪些部分。
而且，正如您已经说过的那样，SVN已经以比代码更具权威性的方式保存了这些信息。所以，如果我是团队中的一员，我总是更喜欢SVN的日志并忽略@author。我敢打赌，无论你采用何种政策，代码都会与现实不同步。遵循不要重复自己的原则，为什么要将这些信息保存在两个地方？
但是，如果某些官僚或政策原因必须将此信息包含在代码中，您是否考虑过在办理登机手续时自动更新代码中的@author标签？您可以使用SVN挂钩 实现此目的。例如，您可以列出按照更改顺序更改给定文件的所有开发人员;或者谁改变了最多;管他呢。或者，如果在{source}代码中强制要求@author发布到外部世界，您可以考虑自动添加@author作为发布版本的一部分（我怀疑您可以从中获取此信息） SVN不知何故）。
至于添加多个类级别@author标签（或其他评论），我会说你会积累很多无益的噪音。 （再次，你有SVN。）
根据我的经验，识别历史变更（比如对一行代码或方法的更改），然后确定与之相关的变更集（以及哪个跟踪单）更有用。然后，您拥有更改的完整上下文：您拥有票证，更改集，您可以在同一票证上找到其他更改集，或者大约在同一时间，您可以找到相关票证，并且您可以看到所有更改形成了这个工作单位。你永远不会从代码中的注释或注释中得到这个。
答案 1 :(得分：20)
您可能需要考虑为什么您希望源代码中包含作者标记。 Apache基金会没有，我同意。
http://www.theinquirer.net/inquirer/news/1037207/apache-enforces-the-removal-of-author-tags
据我所知，这是一种货物崇拜的工作方式，从纸张上印刷来源。使用现代版本控制系统，无论如何都可以在历史中找到这些信息。
答案 2 :(得分：8)
您可以拥有多个@author代码。如果您对某个类进行了一些重大更改，只需添加一个新的@author标记，其中包含您自己的名称。没有必要标记您已完成的更改或将您的名称放在更改中，因为修订历史记录应该能够清楚地显示。
答案 3 :(得分：7)
在拥有大量开发人员的大型和长期项目中，知道ho负责给定代码是有用的，他们可以为您提供额外的信息等。在这种情况下，使用@author标签在文件中包含这样的信息会很方便。不标记谁创建了文件或谁做了一些重要贡献，但谁是该代码的联系人。那些可能是非常不同的人，因为原作者可能已经在不同的项目或多年前离开公司。
我认为在大项目上这种方法可能很方便，但有一点需要注意。保存每个文件的作者信息非常困难，因为文件数量巨大，迟早会失败。越来越多的文件会有过时的信息，开发人员将不再相信这个@author作为信息来源，只会忽略它。
可能有效的解决方案不是将@author保留在每个文件上，而是仅保留每个模块（高级包）。 Javadoc有一个功能，您不仅可以记录文件，还可以记录整个包（See this question for more detail）。
然而，这是一个特殊情况，只要您的项目不大或不老，我建议您省略作者信息。
答案 4 :(得分：2)
我完全同意这是不必要的，您可能不应该添加它。但是，我仍然添加它，就像将签名添加到绘画或adding it to a stamp on a piece of metal in a computer helped design一样。您编写了这段代码，添加名称表明您为它感到骄傲，并且对它的质量充满信心，即使它什么也不做。即使将来进行更改，您也要为在此基础上构建的所有内容奠定基础，并且如果确实要对其进行完全重写，则可以更改，删除或扩展该标签。我同意这是多余的，这要归功于版本控制，但是在版本控制中拥有您的名字并不能令人满意。如果有人只是添加一个“最终”或格式化代码，那么即使他们几乎没有贡献，他们的名字也会受到版本控制。我也同意，这是噪音，因为它没有在代码中添加任何内容，但是确实有点令人讨厌吗？我不这么认为。如果您对此感到合理，那么我认为它可以使项目“更友好”。
答案 5 :(得分：1)
拥有@author标记并拥有多个作者非常方便。甚至Oracle的文档都概述了一个好习惯，那就是让@author上课，以赞扬从事这项工作的特定作者，并在开发过程中需要与他人交谈时追踪事情。如果有多个作者，可以按他们在特定Java文件/类中的贡献顺序列出。是的，有插件并且具有git结构，您可以检查是否可以在代码中精确地看到作者的名字，但是这个想法会引起争议。因为，有时多位作者编辑同一行代码，而可能不会显示两位作者在编辑同一行代码。我启用了插件，它从不显示2位作者姓名来编辑同一行代码。对于大公司来说，建立这种做法很方便。
答案 6 :(得分：0)
如果是公司代码，我不会这样做：我们有VCS。相反，如果它是我的个人仓库的博客文章或代码片段，我会很自豪地添加它，并希望某些复制粘贴的人会发现我的代码有用并且偶然地也复制了我的名字：）
我想这只是我的幽默。
答案 7 :(得分：0)
现在是 2021 年，当我回答这个问题时，距离第一次发布已经将近 8 年了。世界有点不同，它正在全速使用微服务。因此，我将围绕作者身份的整体情绪总结如下：毫无意义。让我解释一下几点：
因此，了解简单的代码编辑和适当的行更改比了解整个班级的知识更重要。