70

I'm wondering about best practices when creating Javadocs. I have a project with many files. Code has been created by many developers. Each file has an annotation @author, so it is obvious who has created a particular class.

But when some other developer adds new code to a file, modifies it, etc., how should he inform the rest of the team that he has created some new function or has modified existing code? In other words, how should we "keep the Javadocs compatible with reality"? ;)

  • Add his name to the existing @author tag? Then, it is easier to identify who to ask in case of any doubts.
  • Add an @author tag to each new method, inner class, etc.?

Of course, since we use SVN, it is easy to investigate who has made what, but for keeping things clear this Javadoc stuff should be taken into consideration as well.

What's the best way to use these @author tags?

4

8 回答 8

73

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

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

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

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

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

于 2013-06-24T08:49:43.923 回答
25

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

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

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

于 2013-06-24T07:19:07.883 回答
11

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

于 2013-06-24T07:15:07.133 回答
9

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

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

可能有效的解决方案不是将@author 保留在每个文件上，而是仅保留每个模块（高级包）。Javadoc 有一个功能，您不仅可以记录文件，还可以记录整个包（有关更多详细信息，请参阅此问题）。

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

于 2016-05-08T07:01:28.500 回答
7

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

于 2019-01-14T11:04:20.393 回答
3

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

于 2019-02-10T21:55:32.663 回答
3

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

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

因此，简单的代码编辑和适当的行更改的知识比整个班级的知识更重要。

这是我对这篇短文消化的班级作者身份的看法。

于 2021-03-28T16:55:42.533 回答
1

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

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

于 2019-04-16T15:52:37.147 回答