源代码管理是否会使 Javadoc 的 @author 和 @since 变得多余？
在大多数团队中，有一条规则规定，@author 和 @since 关键字必须用于所有记录的类，有时甚至是方法。
为了集中精力于重要的事情，我不使用这些关键字，而是依靠这样的事实：我可以使用源代码控制管理系统来确定类的作者是谁以及它何时存在。
我相信 @author 和 @since 来自版本控制尚未普及的时代，我认为它们现在相当多余。您对此有何看法？现代 Java 项目应该使用它们吗？
In most teams there is a rule that says that the @author and @since keywords have to be used for all documented classes, sometimes even methods.
In an attempt to focus on what matters, I don't use these keywords and instead rely on the fact that I can use the source control management system to determine who the author of a class is and since when it exists.
I believe that @author and @since come from a time where version control was not yet common and I think that they are rather redundant by now. How do you think about this? Should modern Java projects use them?
如果你对这篇内容有疑问，欢迎到本站社区发帖提问 参与讨论，获取更多帮助，或者扫码二维码加入 Web 技术交流群。
绑定邮箱获取回复消息
由于您还没有绑定你的真实邮箱，如果其他用户或者作者回复了您的评论，将不能在第一时间通知您！
发布评论
评论（5）
我认为
@author标签实际上混淆了事情。首先，如果不明智地更新，它就会出错。另外，如果你（不是原作者）改半个类怎么办？您是否更新了@author？你加一个吗？如果你只改变类中的几行怎么办？我还认为它促进了代码所有权，我认为这不是一件好事。任何人都应该被允许更改文件。如果有
@author标签，人们会倾向于让作者进行所有更改，而不是自己做，并可能在这个过程中学习一些东西。最后，正如您所说，您的 VCS 中提供了相同的信息，更详细。您在 Javadoc 中添加的任何内容都是重复的。重复是不好的，对吧？
编辑：其他答案提到您可能无法访问 VCS，在这种情况下，
@author标记很有用。我谦虚地不同意。在这种情况下，您很可能正在处理第三方库，或者可能是来自公司内部不同团队的工件。如果是这样的话，创建某个类别的人是谁真的很重要吗？最有可能的是，您只需要知道创建该库的实体，并与他们的联系人交谈。I think the
@authortag actually confuses things. First of all, if it isn't updated judiciously, it becomes wrong. Also, what if you (not being the original author) change half a class? Do you update the@author? Do you add one? And what if you change only a few lines in the class?I also think it promotes code-ownership, which I don't think is a good thing. Anybody should be allowed to change a file. If there's an
@authortag, people will tend to let this author make all the changes instead of doing it themselves and maybe learning something in the process.Finally, as you said, the same information, in much more detail, is available from your VCS. Anything you add in Javadoc is duplication. And duplication is bad, right?
EDIT: Other answers mention the fact that you may not have access to the VCS, and in such cases the
@authortag is useful. I humbly disagree. In such cases, you're most likely dealing with a 3rd party library, or perhaps an artifact from a different team inside your company. If that's the case, does it really matter who the individual was who created a certain class? Most likely, you only need to know the entity who created the library, and talk to their contact person.一方面，Javadoc 可见性通常超越源代码管理可见性。我可以查看 Java 1.1 库的 Javadocs，但据我所知，无法自由地阅读 Sun 那时的版本历史记录。
您所说的好像您的 Javadoc 与您（开发人员）完全隔离，并且没有作为 API 的一部分分发给其他人等。但情况并非总是如此。通常，Javadocs 和 VCS 信息具有完全不同的用途。
对我来说，即使我可以自由访问文件的版本历史记录，我也喜欢能够在源代码中看到它，出于同样的原因，我喜欢解释文件中的奇怪代码的注释，而不必去某个代码块的提交描述。速度更快了。
Well for one thing Javadoc visibility typically transcends source control visibility. I can view the Javadocs for Java 1.1's library but can't to my knowledge freely peruse the Sun's version history from back then.
You're talking as if your Javadocs are completely isolated to you (the developer), and not distributed to others as part of an API, etc. That's not always the case. Usually Javadocs and VCS information serve completely different purposes.
For me, even if I have free access to the version history of a file, I like being able to see it right there in the source, for the same reason that I like comments explaining odd code in the file instead of having to go to the commit description for a certain code block. It's quicker.
我知道我们已经使用过它们，并且只要仔细阅读源代码，它们就非常好。我遇到过不止一种情况，其中 @since 确实非常方便，因为需要做一些工作才能确定添加了哪些版本（通过比较日期等）。
不过，这只是我的经验。我认为 @author 的用处不大，但由于我们可以在创建新类时自动生成这两部分数据，因此让系统为我做这件事似乎并不浪费。
I know that we have used them, and they are really nice when simply perusing the source code. I have had more than one situation where the @since has been really handy to have in there, as it would have taken a bit of work to determine what version something was added in (by comparing dates, etc).
Just my experience however. I think the @author has been less useful, but since we can autogenerate both pieces of data when creating new classes, it doesn't seem like a waste to just let the system do it to me.
我认为只有在需要时才应该执行文档规则。如果将这些内容放入 Java 文档中对您来说是多余的，那么就不要强制执行该规则。一个很重要的情况是，如果有人需要查看该信息并且无法访问您的版本控制
I think documentation rules should be enforced only if you need them. If it's redundant for you to put those in Java Docs, then don't enforce the rule. A case where it would matter is if anyone ever needs to see that information and doesn't have access to your version control
不可以。javadoc 页面的受众可能无法访问您的源代码管理，因此此信息是相关的。
@since 很重要，因为可以查阅旧版本软件的文档。当您看到某个功能何时推出时，您就知道 1) 该功能对您不可用，2) 有充分的理由进行升级。
但是，您可以使用作者的电子邮件地址联系您的团队以获取 @author 标签。
No. The audience of the javadoc pages may not have access to your source control, so this information is relevant.
The @since is important as the documentation may be consulted for older versions of the software. When you can see when a feature was introduced you know 1) that it is unavailable to you and 2) that there is a good reason for upgrading.
You might, however, use an email address for author to contact your team for the @author tag.