Javadoc @author 标记良好实践 [英] Javadoc @author tag good practices

问题描述

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

I'm wondering about best practices when creating Javadocs. I have a project with many files. Code has been created by many developers. Each file has an annotation @author, so it is obvious who has created a particular class.

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

But when some other developer adds new code to a file, modifies it, etc., how should he inform the rest of the team that he has created some new function or has modified existing code? In other words, how should we "keep the Javadocs compatible with reality"? ;)

• 将他的名字添加到现有的 @author 标签中?然后，如果有任何疑问，更容易确定向谁询问.
• 为每个新方法、内部类等添加@author 标签?

• Add his name to the existing @author tag? Then, it is easier to identify who to ask in case of any doubts.
• Add an @author tag to each new method, inner class, etc.?

当然，因为我们使用 SVN，所以很容易调查谁做了什么，但为了清楚起见，还应该考虑这些 Javadoc 内容.

Of course, since we use SVN, it is easy to investigate who has made what, but for keeping things clear this Javadoc stuff should be taken into consideration as well.

使用这些 @author 标签的最佳方式是什么?

What's the best way to use these @author tags?

推荐答案

我认为在大多数情况下 @author 是不需要的噪音.您的 API 的用户不应该 - 并且可能不 - 关心或想知道谁编写了哪些部分.

I would say that for most purposes @author is unwanted noise. The user of your API shouldn't - and probably doesn't - care, or want to know, who wrote which parts.

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

And, as you have already stated, SVN already holds this information in a much more authoritative way than the code can. So if I was one of the team, I would always prefer SVN's log and ignore the @author. I'd bet that the code will get out of sync with reality, whatever policy you adopted. Following the Don't Repeat Yourself principle, why hold this information in two places?

但是，如果出于某些官僚主义或政策原因必须将此信息包含在代码中，您是否考虑过在签入时自动更新代码中的 @author 标签?您可以可能使用 SVN 钩子来实现这一点.例如，您可以按照更改顺序列出更改给定文件的所有开发人员；或者谁改变得最多；管他呢.或者，如果 @author 在您发布到外部世界的(源)代码中是强制性的，您可以考虑自动添加 @author 作为发布版本的一部分(我怀疑您可以以某种方式从 SVN 中获取此信息).

If, however, there is some bureaucratic or policy reason that this information MUST be included in the code, have you considered automatically updating the @author tag in the code on check in? You could probably achieve this with an SVN hook. You could for example list all the developers who changed a given file in the order they changed it; or who changed it most; or whatever. Or, if the @author is mandated in (source) code you release to the outside world, you could consider adding the @author automatically as part of the release build (I suspect you could get this information out of SVN somehow).

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

As for adding more than a single class level @author tag (or other comment), I'd say you'd be accumulating a lot of unhelpful noise. (Again, you have SVN.)

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

In my experience it is much more useful to identify a historical change (say a change to a line of code, or a method), then to work out which change set this relates to (and which track ticket). Then you have the full context for the change: you have the ticket, the change set, you can find other change sets on the same ticket, or around the same time, you can find related tickets, and you can see ALL the changes that formed that unit of work. You are never going to get this from annotation or comments in code.

这篇关于Javadoc @author 标记良好实践的文章就介绍到这了，希望我们推荐的答案对大家有所帮助，也希望大家多多支持IT屋！