Javadoc @author标签良好实践

fafcakar  于 2023-06-28  发布在  Java
关注(0)|答案(9)|浏览(125)

我想知道创建Javadoc时的最佳实践。我有一个有很多文件的项目。代码是由许多开发人员创建的。每个文件都有一个注解@author,所以很明显是谁创建了一个特定的类。
但是,当其他开发人员向文件中添加新代码,修改它等时,他应该如何通知团队的其他成员他已经创建了一些新函数或修改了现有代码?换句话说,我们应该如何“使Javadoc与现实兼容”?;)

  • 将他的名字添加到现有的@author标记中?然后,更容易确定在有任何疑问的情况下询问谁。
  • 为每个新方法、内部类等添加@author标记?

当然,因为我们使用SVN,所以很容易调查谁做了什么,但是为了保持清晰,也应该考虑Javadoc的东西。
使用这些@author标签的最佳方式是什么?

ee7vknir

ee7vknir1#

我会说,对于大多数目的,@author是不必要的噪音。你的API的用户不应该--也可能不关心,或者想知道是谁写了哪些部分。
而且,正如您已经说过的,SVN已经以比代码更权威的方式保存了这些信息。因此,如果我是团队中的一员,我总是更喜欢SVN的日志,而忽略@author。我敢打赌,无论你采取什么政策,代码都会与现实脱节。遵循“不要重复自己”的原则,为什么要把这些信息放在两个地方呢?
但是,如果由于某些官僚或政策原因,这些信息必须包含在代码中,您是否考虑过在签入时自动更新代码中的@author标记?你可以用一个SVN钩子来实现这一点。例如,您可以按照更改文件的顺序列出所有更改了给定文件的开发人员;或者谁改变的最多什么的或者,如果@author在您发布到外部世界的(源)代码中是强制性的,您可以考虑将@author自动添加为发布构建的一部分(我怀疑您可以通过某种方式从SVN获得此信息)。
至于添加多个类级别的@author标记(或其他注解),我认为您会积累大量无用的噪音。(同样,你有SVN。)
根据我的经验,识别一个历史变更(比如对一行代码或一个方法的变更),然后找出这与哪个变更集(以及哪个跟踪票)相关,这要有用得多。然后,您就有了更改的完整上下文:你有了票证、变更集,你可以在同一票证上找到其他变更集,或者在同一时间,你可以找到相关票证,你可以看到构成该工作单元的所有变更。您永远不会从代码中的注解或注解中获得这一点。

vbkedwbf

vbkedwbf2#

您可能需要考虑 * 为什么 * 您需要在源代码中使用作者标签。Apache基金会不同意,我也同意。
https://web.archive.org/web/20150226035235/www.theinquirer.net/inquirer/news/1037207/apache-enforces-the-removal-of-author-tags
据我最好的理解,这是一个货物邪教的工作方式,从当来源印在纸上。在现代版本控制系统中,无论如何都可以在历史记录中找到这些信息和更多信息。

btxsgosb

btxsgosb3#

可以有多个@author标记。如果你对一个类做了一些大的修改,只需要添加一个新的@author标记,其中包含你自己的名字。没有必要标记您所做的更改或将您的名字放在更改周围,因为修订历史应该能够清楚地显示。

wnrlj8wa

wnrlj8wa4#

在有很多开发人员的大型长期项目中,知道谁负责给定的代码,谁可以为您提供额外的信息等是很有用的。在这种情况下,使用@author标记在文件中包含这样的信息会很方便。不标记谁创建了文件或谁做出了一些主要贡献,而是谁是该代码的联系人。这些人可能是非常不同的人,因为原作者可能已经在不同的项目上,或者几年前就离开了公司。
我认为在大型项目中,这种方法可能很方便,但有一个警告。保持每一个文件的作者信息是非常困难的,因为有大量的文件,迟早会失败。越来越多的文件将包含过时的信息,开发人员将不再信任这个@author作为信息来源,并将忽略它。
一个可行的解决方案是,不要在每个文件上都保留@author,而只在每个模块(高级包)上保留。Javadoc有一个特性,你不仅可以记录文件,还可以记录整个包(See this question for more detail)。
然而,这是一个特殊的情况,只要你的项目不是那么大或旧,我reccomend ommiting作者信息。

chhqkbe1

chhqkbe15#

我完全同意这是不必要的,你可能不应该添加它。但是我还是添加了它,我认为这就像在一幅画上添加签名,或者adding it to a stamp on a piece of metal in a computer helped design。你写了那段代码,加上你的名字表明你为它感到自豪,你对它的质量有信心,即使它没有做任何其他事情。即使它在将来被更改,您也为构建在其上的所有内容奠定了基础,并且如果它真的被完全重写,则标记可以被更改,删除或扩展。我同意由于版本控制,它是多余的,但是在版本控制中有你的名字并不令人满意。如果某人只是添加了一个“final”或格式化了代码,他们的名字将在版本控制中,即使他们几乎没有贡献。我也同意它是噪音,因为它没有给代码添加任何东西,但是它真的有一点点明显的烦人吗?我不这么认为如果你是合理的,我认为它可以使一个项目“更友好”,如果这是有意义的。

4uqofj5v

4uqofj5v6#

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

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

因此,了解简单的代码编辑和适当的行更改比了解整个类更重要。
以下是我对class authorship digested to the short article的看法。

q9rjltbz

q9rjltbz7#

使用@author标签和多个作者非常方便。甚至Oracle的文档也指出,在类的顶部添加@author是一个很好的做法,可以给予功劳归于完成这项工作的特定作者,如果在开发过程中需要与某人交谈,也可以跟踪事情。如果有多个作者,可以按照他们对特定Java文件/类的贡献顺序列出。是的,有插件和git结构,你可以检查可以看到作者的名字在代码中准确地挂起,但这个想法将是有争议的。因为,有时多个作者编辑同一行代码,可能不会显示两个作者编辑同一行代码。我有插件启用,它从来没有显示2作者的名字编辑同一行代码。对于大公司来说,建立这种做法很方便。

vwkv1x7d

vwkv1x7d8#

如果是公司代码,我不会这样做:我们有VCS。相反,如果是一篇博客文章或我的个人代码库的代码片段,我会自豪地添加这一点,并希望一些复制粘贴的家伙会发现我的代码有用,并不小心,复制我的名字:)
只是我的幽默,我猜。

pkbketx9

pkbketx99#

this答案的基础上,通过从2004年的帖子中挖掘链接,我找到了this(粘贴在下面)。它来自Dirk-Willem van Gulik,他是Apache软件基金会的创始人之一,所以我假设他对停止使用@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标签在某种程度上实际上是“错误的”;在大多数情况下,它只是表示哪个人编写了该代码的第一个框架;但随后它被修复,同行评审并被整个社区关注。也不要忘记你的社区中有很多人帮助你进行QA,文档,用户反馈等等。把一个人放在(热)座位上,因为本质上是一个团队的努力是不太正确的。
查看几个tomcat文件的CVS日志:每一个30行的块似乎有至少5个人的提交;中位数为6,平均值为9。这些任意块上的@author标记的平均数量大约是0.5。这还不包括QA、文档、邮件列表建议、错误解决方案和用户支持。也就是说,那些使tomcat成为一个受支持的产品的东西。
其次,我们作为ASF品牌“出售”的是一个代码库,它是由一个可持续发展的团队进行同行评审、质量控制和创建的,该团队将在志愿者的来来往往中生存下来。一个知识普遍共享而不仅仅依赖于一个人的地方。这就是为什么大公司、政府等使用Apache比使用大多数其他开源软件要少很多顾虑的关键原因之一;我们减轻了人们的担忧,即它依赖于一个人,并且可以在没有警告的情况下崩溃或分叉。
最后-很多开发人员确实生活在你可能会被起诉的国家。ASF可以提供一定程度的保护;但这是基于一个关键的前提,即有监督和同行审查。我们运送的是一个社区产品;一切都是由社会支持的,不能归咎于一个人。每个提交都有同行评审;任何一个版本都需要+1,并得到整个社区的支持。@author标签必然是不完整的,因此不能准确地描述情况。任何暗示或暗示部分代码不是社区产品都会使防御变得更加复杂和昂贵。我们不想临时任何人-而是提出一个干净的图片没有瑕疵或容易去的。
给予它一个积极的倾斜;为这种文化感到自豪;为自己是一个更大的高质量的组织的一部分而感到自豪。你们每个人都不只是写了几行用@author标记包围的讨厌的代码;但是在整个事情的工作中起着重要的作用!如果你曾经试图理解为什么Cocoon能走到这一步,而其他商业/开源项目却没有,那么请看看这里;质量和长期稳定性。
保重,玩得开心,
Dw
在追踪这一点时,我遇到了一些反对这一点的博客文章,有些赞成。这是一个非常小的样本量,但我认为公平地说,这至少是一个有争议的变化-一些人希望他们留下来。也就是说,在2022年,我真的看不到它们被使用。(记住,这封邮件是2004年的)你甚至提到了SVN的历史(但现在可能Git是更常用的工具),甚至在这封邮件中他们提到了CVS日志(另一个源代码控制工具)。也许今天的源代码控制工具更容易使用,谁知道呢。
我觉得仍然可能有一些奇怪的用例是有意义的,但我不认为“我写了(或修改了)这个,所以我把自己作为@author”的标准想法是必要的。我目前有一个question on Code Review关于使用它的知识共享属性和(在我看来)我认为这是一个很好的使用,但我很难称之为一个公认的良好做法(但我不认为这是伤害)。

相关问题