Javadoc @author标记了良好实践

Question

我想知道创建Javadocs时的最佳实践.我有一个包含许多文件的项目.代码已由许多开发人员创建.每个文件都有一个注释@author,因此很明显谁创建了一个特定的类.

但是当其他开发人员向文件添加新代码,修改它等等时,他应该如何通知团队的其他成员他已经创建了一些新功能或修改了现有代码？换句话说,我们应该如何"让Javadocs与现实保持一致"？;)

• 将他的名字添加到现有@author标签？然后,如果有任何疑问,更容易识别要询问的人.
• @author为每个新方法,内部类等添加标记？

当然,由于我们使用SVN,很容易调查谁做了什么,但为了保持清楚,这个Javadoc的东西也应该被考虑在内.

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

Answer 1

我会说,大多数用途@author都是不必要的噪音.您的API的用户不应该 - 也可能不 - 关心或想知道谁编写了哪些部分.

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

但是,如果某些官僚或政策原因必须将此信息包含在代码中,您是否考虑@author过在办理登机手续时自动更新代码中的代码？你可以或许与SVN钩子实现这一目标.例如,您可以列出按照更改顺序更改给定文件的所有开发人员; 或者谁改变了最多; 管他呢.或者,如果@author在(源)代码中强制要求释放到外部世界,您可以考虑@author自动添加自动作为发布版本的一部分(我怀疑您可以以某种方式从SVN中获取此信息).

至于添加多个类级别@author标签(或其他评论),我会说你会积累很多无益的噪音.(再次,你有SVN.)

根据我的经验,识别历史变化(比如对一行代码或方法的更改),然后确定与之相关的变更集(以及哪个跟踪单)更有用.然后,您拥有更改的完整上下文:您拥有票证,更改集,您可以在同一票证上找到其他更改集,或者大约在同一时间,您可以找到相关票证,并且您可以看到所有更改形成了这个工作单位.您永远不会从代码中的注释或注释中获取此信息.

Answer 2

您可能想要考虑为什么要在源中使用作者标记.Apache基金会没有,我同意.

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

据我所知,这是一种货物崇拜的工作方式,从纸张上印刷来源.使用现代版本控制系统,无论如何都可以在历史中找到这些信息.

Answer 3

您可以拥有多个@author标签.如果您对某个类进行了一些重大更改,只需添加一个@author带有您自己名称的新标记即可.没有必要标记您已完成的更改或将您的名称放在更改中,因为修订历史记录应该能够清楚地显示.

Answer 4

在拥有大量开发人员的大型和长期项目中,知道ho负责给定代码,谁可以为您提供额外信息等是很有用的.在这种情况下,使用@author标签在文件中包含这样的信息会很方便.不标记谁创建了文件或谁做了一些重要贡献,但谁是该代码的联系人.那些可能是非常不同的人,原作者可能已经在不同的项目或多年前离开公司.

我认为在大项目中这种方法可能很方便,但有一点需要注意.保存每个文件的作者信息非常困难,因为存在大量文件,迟早会失败.越来越多的文件将有过时的信息,开发人员将不再相信这个@author作为信息来源,并且会忽略它.

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

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

Answer 5

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

Answer 6

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

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

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

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