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

问题描述

我想知道创建Javadocs时的最佳实践。我有一个包含许多文件的项目。代码已由许多开发人员创建。每个文件都有一个注释 @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.

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

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屋！