Javadoc @author 标签良好实践答案

【问题标题】：Javadoc @author tag good practicesJavadoc @author 标签良好实践
【发布时间】：2013-06-20 15:03:27
【问题描述】：

我想知道创建 Javadocs 时的最佳实践。我有一个包含许多文件的项目。许多开发人员已经创建了代码。每个文件都有一个注解@author，所以很明显是谁创建了一个特定的类。

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

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

当然，因为我们使用 SVN，所以很容易调查谁做了什么，但为了清楚起见，这些 Javadoc 的东西也应该考虑在内。

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

【问题讨论】：

SVN 在这种情况下是什么意思？
@inetphantom SVN（Subversion）是版本控制系统的一个例子。更多详情请见subversion.apache.org

标签： java javadoc author

【解决方案1】：

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

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

但是，如果出于某些官僚或政策原因必须将此信息包含在代码中，您是否考虑过在签入时自动更新代码中的@author 标签？您可以可能使用 SVN 挂钩来实现这一点。例如，您可以按更改给定文件的顺序列出所有更改给定文件的开发人员；或者谁改变最多；管他呢。或者，如果@author 是在您发布给外界的（源）代码中强制使用的，您可以考虑将@author 作为发布版本的一部分自动添加（我怀疑您可以通过某种方式从SVN 中获取此信息）。

至于添加多个类级别 @author 标记（或其他评论），我会说你会积累很多无用的噪音。（同样，你有 SVN。）

根据我的经验，识别历史更改（例如对代码行或方法的更改），然后确定与哪个更改集相关（以及哪个跟踪单）会更有用。然后你就有了变更的完整上下文：你有工单，变更集，你可以在同一个工单上找到其他的变更集，或者大约在同一时间，你可以找到相关的工单，你可以看到所有的变更形成了该工作单元。你永远不会从代码中的注释或 cmets 中得到这个。

【讨论】：

@tvshajeer：没有注释，只需使用 git 或 svn 来检查谁更改了什么。作者注释还减轻了集体代码所有权的想法
不想要的是谁？隐藏这些信息有什么可能的价值？
@VGR 我工作的代码库之一有大约 1,000,000 行 Java 开发超过十年，大约有 8,000 个类。大多数 do 都有作者标签。其中：他们通常只命名创建类的人；被点名的 5 人中有 4 人不再为公司工作；从那以后，很多都被修改得如此之多，以至于无论如何命名的开发人员都无法识别它们；许多是错误的，因为它们是在类派生自类似类时复制的。在审查源文件或生成的文档时，它们会浪费屏幕空间，从而妨碍理解。
@VGR 也就是说，我对开源项目中的作者标签没有任何问题，例如，它们用于归因于信用。或者在一个库中，不同的子包实际上是由不同的人开发的（因此他们真的确实告诉你一些有用的东西）。但我的经验表明，在大多数实际项目中，大多数时候，它们实际上只是噪音（或虚荣心）。
很多项目的源代码系统都发生了变化，所有作者的历史都丢失了

【解决方案2】：

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

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

据我所知，这是一种货物崇拜的工作方式，从资源印在纸上开始。借助现代版本控制系统，这些信息以及更多信息无论如何都可以在历史记录中找到。

【讨论】：

【解决方案3】：

您可以拥有多个@author 标签。如果您对某个类进行了一些重大更改，只需添加一个新的@author 标记，其中包含您自己的名称。无需标记您所做的更改或在更改周围加上您的名字，因为修订历史应该能够清楚地显示。

【讨论】：

【解决方案4】：

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

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

可能有效的解决方案不是将@author 保留在每个文件上，而是仅保留每个模块（高级包）。 Javadoc 有一个功能，您不仅可以记录文件，还可以记录整个包 (See this question for more detail)。

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

【讨论】：

很高兴了解包 cmets ;)
不是在每个源文件中。

【解决方案5】：

我完全同意这是不必要的，您可能不应该添加它。但是我仍然添加它，我认为它就像在绘画中添加签名，或adding it to a stamp on a piece of metal in a computer helped design。你写了那段代码，加上你的名字表明你为它感到自豪，并且你对它的质量充满信心，即使它什么也没做。即使它在未来发生了变化，你也为建立在它之上的一切奠定了基础，如果它真的被完全重写，标签可以被改变、删除或扩展。我同意由于版本控制，它是多余的，但是在版本控制中拥有你的名字并不那么令人满意。如果有人只是添加“最终”或格式化代码，他们的名字将在版本控制中，即使他们几乎没有贡献。我也同意它是噪音，因为它不会在代码中添加任何内容，但是它真的有点烦人吗？我不这么认为。如果你是合理的，我认为它可以使项目“更友好”，如果这有意义的话。

【讨论】：

您好，感谢您回答这个问题 :) 我可以告诉您，从某种角度来看，我不再喜欢使用这个标签了。将它编码为团队工作，只要这样的标签可以 - 正如你提到的 - 被视为一种画家的签名，我认为代码不适合这种行为;）当然可能存在这样的情况方法是合理的（对于 exanoke 将整个团队添加为作者，以便其他团队知道谁负责某些功能）但根据经验，我不会经常使用它。 “如果你是合理的” - 同意 - 这是这里的关键点；）
是的，这在很大程度上取决于您所在的环境/团队。默认情况下不应使用它，但在某些环境中它可能会略微提高质量或满意度。

【解决方案6】：

拥有@author 标签并拥有多个作者非常方便。甚至 Oracle 的文档也概述了将@author 放在课堂上以表彰完成这项工作的特定作者并在开发过程中需要与某人交谈时追踪事情的好习惯。如果有多个作者，则可以按照他们对特定 java 文件/类的贡献的顺序列出他们。是的，有插件和 git 结构，你可以检查可以准确地看到代码中挂着的作者的名字，但是这个想法会引起争议。因为，有时多个作者编辑同一行代码，可能不会显示两个作者编辑同一行代码。我启用了插件，它永远不会显示 2 个作者姓名来编辑同一行代码。对于大公司，建立这种做法很方便。

【讨论】：

【解决方案7】：

现在是 2021 年，当我回答这个问题时，距离首次发布已有近 8 年的时间。世界有点不同，它正在全速使用微服务。因此，我将围绕作者身份的整体情绪总结如下：毫无意义。让我解释几点：

最广泛的软件或组织项目是由多个作者开发的，而不是个人。
大部分软件都在 Git、CI/CD 中进行版本控制，并且可以访问云端。
高级 IDE 可以极大地可视化代码更改。代码更改比整个类源代码更重要。
处理由代码更改引起的错误远比处理由使用错误的类版本引起的错误重要。
除非软件是库、IP/商业软件、定期发布的框架，否则作者身份没有任何意义。
您使用/处理的源代码的作者很可能不在或从未在您的组织中工作。
在作者声明中保持适当的作者贡献比例会导致额外的工作量为 0。没有人想要那样。

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

这是我对class authorship digested to the short article的看法。

【讨论】：

【解决方案8】：

如果是公司代码，我不会那样做：我们有 VCS。相反，如果它是我个人 repo 的博客文章或代码 sn-ps，我会自豪地添加它，并希望一些复制粘贴的人会发现我的代码有用并且不小心，也复制我的名字:)

我猜这只是我的幽默类型。

【讨论】：