源代码管理是否使Javadoc'；s@author和@因为冗余？

在大多数团队中，有一条规则规定@author和@since关键字必须用于所有文档化的类，有时甚至是方法

为了专注于什么是重要的，我没有使用这些关键字，而是依赖于这样一个事实，即我可以使用源代码管理系统来确定类的作者是谁以及从什么时候起它就存在了

---

我相信@author和@since来自一个版本控制还不普遍的时代，我认为它们现在已经相当多余了。你对此有何看法？现代Java项目应该使用它们吗？

我知道我们已经使用过它们，而且只要仔细阅读源代码，它们就非常好了。我曾经有过不止一种情况，@since在其中非常方便，因为要确定添加了什么版本（通过比较日期等），需要做一些工作

---

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

我认为只有在需要时才应该强制执行文档规则。如果将它们放在Java文档中是多余的，那么不要强制执行该规则。一个重要的例子是，如果有人需要查看该信息，但没有访问您的版本控制的权限，那么Javadoc可见性通常会超越源代码控制可见性。我可以查看JavadocsforJava1.1的库，但据我所知，不能自由地阅读Sun当时的版本历史

您所说的好像您的javadoc对您（开发人员）是完全隔离的，而不是作为API的一部分分发给其他人，等等。情况并非总是这样。通常，Javadocs和VCS信息的用途完全不同

---

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

我认为

@author

标签实际上混淆了事情。首先，如果不明智地更新，它就会出错。另外，如果你（不是原作者）更改了半个类怎么办？您是否更新了

@author

？你加一个吗？如果你在课堂上只换几行怎么办

我还认为它促进了代码所有权，我认为这不是一件好事。应该允许任何人更改文件。如果有一个

@author

标签，人们会倾向于让这个作者来做所有的更改，而不是自己去做，也许在这个过程中会学到一些东西

最后，正如你所说，同样的信息，更详细的信息，可以从你的风投。在Javadoc中添加的任何内容都是重复的。复制是不好的，对吗

---

编辑：其他答案提到您可能无法访问VCS，在这种情况下，

@author

标签很有用。我谦逊地不同意。在这种情况下，您最有可能处理的是第三方库，或者可能是来自公司内部不同团队的工件。如果是这样的话，创建某个类的个人是谁真的很重要吗？很可能，您只需要知道创建库的实体，并与他们的联系人交谈。

否。javadoc页面的读者可能无法访问您的源代码管理，因此此信息是相关的

@since很重要，因为对于较旧版本的软件，可以参考文档。当您看到某项功能是在何时引入的时，您就知道1）该功能对您不可用，2）有很好的升级理由

---

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

一些版本控制系统甚至支持填写作者信息等，这样您就可以在不引入冗余信息的情况下从此类用例中受益。这通常必须显式启用，以防止在不需要替换关键字标记的情况下损坏文件。例如，这就是它在Subversion中的工作方式@阿基米德：我发现这是一个混合包。我通常更喜欢作者更加静态。否则，您将进入这样一个场景：有人碰巧纠正了文件中的一个打字错误，而现在他们是文件的“作者”。我们公司自动替换了它，我发现它没那么有用。我同意jqno的观点，@author标签本身并没有提供很多好处。是的，这确实是一个问题。。。然而，我想不出任何其他的方法来解决这个问题的软件令人满意。。。对于非二进制文件，可以考虑一个扩展的authors关键字或其参数化版本，根据从VCS怪操作中得到的贡献列出最相关的作者（这通常非常昂贵，因此在实践中并不真正有用）。所以，看来要把事情做好，唯一的办法就是自己动手！；-）我一点也不反对@Author标签评估-+1复制只适用于冗余，就像在纠错代码中一样。完全同意

@Author

标签的无用性。不过，

@since

标签在公共图书馆文档中很方便。“为什么我不能使用它？啊，它是在4.9中添加的，但我有4.2…”同意

@的有用性，因为
，但是是的。。。谁在乎哪个人编写了特定的类或方法？