源代码管理是否使Javadoc的@author和@since冗余？

Question

在大多数团队中都有一条规则，即@author和@since关键字必须用于所有记录的类，有时甚至是方法。

为了专注于重要的事情，我不使用这些关键字，而是依赖于我可以使用源代码管理系统来确定类的作者是谁以及何时存在。< / p>

我相信@author和@since来自版本控制尚未普及的时代，我认为它们现在已经相当多余了。你觉得这个怎么样？现代Java项目应该使用它们吗？

Answer 1

我认为@author标签实际上会混淆事物。首先，如果没有明智地更新，那就错了。另外，如果你（不是原作者）改变了一半的课程怎么办？你更新了@author吗？你加一个吗？如果你只改变班上的几行呢？

我也认为它促进了代码所有权，我认为这不是一件好事。应该允许任何人更改文件。如果有一个@author标签，那么人们会倾向于让这位作者进行所有更改，而不是自己动手做，也许会在这个过程中学习一些东西。

最后，正如您所说，您的VCS可以获得相同的信息，更详细。你在Javadoc中添加的任何内容都是重复的。复制很糟糕，对吗？

编辑：其他答案提到您可能无权访问VCS，在这种情况下，@author标记很有用。我谦卑地反对。在这种情况下，您最有可能处理第三方库，或者可能是公司内部不同团队的工件。如果是这样的话，那个人是谁创造了某个班级真的很重要吗？最有可能的是，您只需要知道创建图书馆的实体，并与他们的联系人交谈。

Answer 2

一方面，Javadoc可见性通常超越源控制可见性。我可以查看Javadocs for Java 1.1的库，但据我所知，不能自由地仔细阅读Sun的版本历史。

你说的就好像你的Javadocs完全与你（开发者）隔离，而不是作为API的一部分分发给其他人等等。情况并非总是如此。通常Javadocs和VCS信息用于完全不同的目的。

对我来说，即使我可以自由访问文件的版本历史记录，我也希望能够在源代码中看到它，原因与我喜欢在文件中解释奇怪代码的注释相同而不是转到某个代码块的提交描述。它更快。

Answer 3

我知道我们已经使用过它们，只是简单地阅读源代码就非常好了。我有不止一种情况，因为@since在那里非常方便，因为它需要一些工作来确定添加了什么版本（通过比较日期等）。

只是我的经验。我认为@author不太有用，但是因为我们可以在创建新类时自动生成这两个数据，所以让系统对我这样做似乎并不浪费。

Answer 4

没有。 javadoc页面的受众可能无法访问您的源代码管理，因此这些信息是相关的。

@since很重要，因为可以查看旧版本软件的文档。当您看到某个功能何时推出时，您知道1）您无法使用该功能，并且2）有充分的理由进行升级。

但是，您可以使用作者的电子邮件地址与您的团队联系以获取@author标记。

Answer 5

我认为文档规则只有在您需要时才能执行。如果您将这些内容放在Java Docs中是多余的，那么请不要强制执行该规则。重要的是，如果有人需要查看该信息并且无法访问您的版本控制