Javadoc@author 标签良好做法

你可以有多个 @author标签。如果你对一个类做了一些大的改变，只需添加一个新的 @author标记，其中包含你自己的名字。不需要标记已经完成的更改，也不需要在更改周围加上您的名字，因为修订历史应该能够清楚地显示这一点。

您可能想考虑 为什么，您想在源代码中使用 author 标记。阿帕奇基金会没有，我也同意。

Https://web.archive.org/web/20150226035235/www.theinquirer.net/inquirer/news/1037207/apache-enforces-the-removal-of-author-tags

据我最好的理解，这是一种货物邪教的工作方式，从来源被打印在纸上。随着现代版本控制系统这一信息和更多的可以在历史中找到无论如何。

我会说，在大多数情况下，@author是不必要的噪音。API 的用户不应该——可能也不会——关心或想知道是谁编写了哪些部分。

并且，正如您已经说过的，SVN 已经以比代码更权威的方式保存了这些信息。因此，如果我是团队中的一员，我总是更喜欢 SVN 的日志，而忽略 @author。我敢打赌，不管你采取什么政策，代码都会与现实脱节。遵循“不要重复自己”的原则，为什么要把这些信息放在两个地方呢？

但是，如果出于某些官僚主义或政策原因，这些信息必须包含在代码中，您是否考虑过在签入时自动更新代码中的 @author标记？您可以使用一个 SVN 挂钩来实现 可能吧。例如，您可以列出所有按顺序更改给定文件的开发人员; 或者更改次数最多的开发人员; 或者其他任何人。或者，如果 @author是在您向外部世界发布的(源)代码中强制使用的，那么您可以考虑自动添加 @author作为发布版本构建的一部分(我怀疑您可以通过某种方式从 SVN 获得这些信息)。

至于添加一个以上的类级别 @author标签(或其他注释) ，我想说你会积累了很多没有帮助的噪音。(再说一次，你有 SVN。)

根据我的经验，识别历史变更(比如对代码行或方法的变更) ，然后确定这个变更集与哪个变更集相关(以及跟踪票据) ，这样做更有用。然后你就有了变更的完整上下文: 你有了票据，变更集，你可以在同一张票据上找到其他的变更集，或者在同一时间，你可以找到相关的票据，你可以看到所有形成这个工作单元的变更。您永远不会从代码中的注释或注释中获得这些信息。

在有大量开发人员的真正大型和长期运行的项目中，了解谁对给定的代码负责、谁可以为您提供额外的信息等是很有用的。在这种情况下，使用@author 标记在文件中包含这样的信息会很方便。不是标记谁创建了这个文件或者谁做了一些主要贡献，而是标记谁是这个代码的联系人。这些可能是非常不同的人，因为原作者可能已经在不同的项目或离开公司多年前。

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

可行的解决方案是，不在每个文件上都保留@author，而是仅保留每个模块(高级包)。Javadoc 有一个特性，不仅可以记录文件，还可以记录整个包(更多细节请参见这个问题)。

然而，这是一个特殊的情况，只要您的项目不是那么大或老，我建议省略作者信息。

我完全同意这是不必要的，你也许不应该添加它。然而我仍然添加它，我看到它就像添加一个签名到绘画，或 将它加入到电脑中一块金属的印章中，有助于设计。你写了那段代码，加上你的名字表示你为它感到骄傲，你对它的质量有信心，即使它没有做其他事情。即使它在未来发生了变化，您也为构建在它之上的所有内容奠定了基础，如果它真的被完全重写，标记可以被更改、删除或扩展。我同意，由于版本控制，这是多余的，但是将您的名字放在版本控制中几乎不能令人满意。如果有人只是添加了“ final”或格式化了代码，他们的名字就会出现在版本控制中，即使他们几乎没有贡献。我也同意它是噪音，因为它不会给代码增加任何东西，但是它真的有那么一点点明显的烦人吗？我不这么认为。如果你对此有理有据，我认为它可以使一个项目“更友好”，如果这是有意义的。

拥有@author 标签并拥有多个作者非常方便。甚至 Oracle 的文档也指出，让@author 位居前列是一种很好的做法，既可以表彰完成这项工作的特定作者，也可以在开发过程中跟踪某人需要交谈的内容。如果有多个作者，那么可以按照他们在特定的 java 文件/类中的贡献顺序列出他们。是的，有插件和与 git 结构，你可以检查可以看到作者的名字挂在代码精确，但这个想法将是有争议的。因为，有时多个作者编辑同一行代码，并且可能不会显示两个作者编辑同一行代码。我有插件启用，它从来没有显示2个作者的名字编辑相同的代码行。对于大公司来说，建立这种实践是很方便的。

如果这是公司代码，我不会这样做: 我们有 VCS。相反，如果它是一篇博客文章或者我个人回购的代码片段，我会自豪地加上这个，并希望一些复制粘贴的家伙会发现我的代码有用，并意外地复制我的名字:)

我猜这就是我的幽默。

现在是2021年，当我回答这个问题的时候，距离第一次出版已经过去了将近8年。这个世界有点不同，它正在全力使用微服务。因此，我想总结作者的整体情绪如下: 毫无意义。让我解释几点:

• 大多数广泛使用的软件或组织项目都是由多个作者开发的，而不再是个人。
• 大多数软件都是基于 Git、 CI/CD 和云计算的版本。
• 高级 IDE 可视化代码变更。代码变更比整个类源代码更重要。
• 处理由代码更改引起的 bug 要比处理由使用错误的类版本引起的 bug 重要得多。
• 除非该软件是一个库，IP/商业软件，定期发布的框架，作者身份是没有意义的。
• 很有可能您使用/编写的源代码的作者不在您的组织中工作，或者从未在您的组织中工作过。
• 在作者声明中保持作者贡献的适当比例会导致额外的努力，而收益为0。没有人希望这样。

因此，了解简单的代码编辑和适当的行更改比了解整个类更重要。

以下是我对 课堂作者对短文的理解的看法。

基于 这个的答案和从2004年的帖子中挖掘的链接，我发现了 这个(粘贴在下面)。它来自于 Apache软件基金会的创始人之一 Dirk-Willem van Gulik，所以我猜想他对于停止使用 @author标签的决定有一些意见。

List:       xml-cocoon-dev Subject:    Re: @author tags (WAS: RE: ASF
Board Summary for February 18, 2004) From:       Dirk-Willem van Gulik
<dirkx () asemantics ! com> Date:       2004-02-27 10:33:32
Message-ID: 63E38432-6910-11D8-BA7E-000A95CDA38A () asemantics ! com

2004年2月27日上午12:45，Conal Tuohy 写道:

我认为 ASF 不应该阻止开发人员保持有用性 关于源文件中代码的元数据 把元数据放在代码中? 这使得它更有可能是 使用和保持更新比如果它被储存在其他地方，恕我直言。

看待这个问题的一种方式是,@author 标签在某种程度上是事实 “错误”; 在大多数情况下，它只是表明哪个人写了第一个 代码的骨架，但随后它是修复，同行审查 而且被整个社会所关注。也不要忘记很多 在你的社区中帮助质量保证、文件、, 把一个人放在(烫手的)座位上 本质上是一个团队的努力是不完全正确的。

查看几个 tomcat 文件的 CVS 日志: 每个块为30 行似乎有至少5人的提交; 具有中间值 的平均值为6，平均值为9 这些任意块大约是0.5这还不包括质量保证, 文档，邮件列表的建议，错误解决方案，用户支持。 也就是说，那些使 Tomcat 成为一个非常好的支持产品的东西。

其次，我们所“销售”的 ASF 品牌是一个代码库，这是同行 评审、质量控制和由可持续发展的团队创建 会在志愿者的来来往往中幸存下来 是普遍共享的，而不仅仅依赖于一个个体。 这就是为什么大公司、政府等 使用 apache 比使用大多数其他 open 要少得多的顾虑 我们减轻了它依赖于一个人的担忧, 从一开始就能毫无预兆地内爆或分叉。

最后，许多开发人员确实生活在你可以得到的国家 ASF 可以提供一定程度的保护，但这是 基于关键的前提，有监督和同行审查。 我们运送的是社区产品，所有东西都是 不能归咎于任何一个人。 每次提交都会得到同行评审; 每次发布都要求 + 1 s，并且是 @ author 标签是必要的 不完整，因此描述的情况不准确。任何暗示或 建议部分代码不是社区产品 防御更加复杂和昂贵。我们不希望任何人临时- 而是呈现一个干净的图片，没有瑕疵或容易去的。

并给予这一积极的倾向; 为这一文化感到自豪; 为自己成为一个更大的组织的一部分而感到自豪 你不仅仅是写了几行烦人的代码 @ author tag; 但是在什么地方有助于得到整件事情的工作 如果你想知道为什么茧做了这个 远，和其他商业/开源项目没有，那么做看 质量和长期稳定的感觉。

保重，玩得开心,

DW

在追踪这个问题的过程中，我发现了一些反对这个问题的博客文章和一些赞成这个问题的博客文章。这是一个非常小的样本规模，但我认为公平地说，这至少是一个有争议的变化——一些人希望他们留下来。尽管如此，到2022年，我还真没看到它们被使用过。(记住，这是2004年的邮件。)您甚至自己提到了 SVN 历史记录(但是现在 Git 可能是更常用的工具) ，甚至在这封邮件中也提到了 CVS 日志(另一个源代码控制工具)。也许今天的源代码控制工具更容易使用，谁知道呢。

我觉得可能仍然有一些奇怪的用例有意义，但我不认为标准的想法“我写(或修改) ，所以我把自己作为 @author”是必要的。我目前有一个关于使用它来获得知识共享归因的 守则检讨问题，(在我看来)我认为这是一个很好的使用方法，但我很难说这是一个被广泛接受的好做法(但我不认为这会造成伤害)。