什么是处理/格式的Javadoc和注释在code的最好方法？ [英] What's the best way to handle/format Javadoc and annotations in code?

问题描述

我看着对面这个论坛，我GOOGLE了这个，我不知道什么是处理Javadoc和注解，在同一类一起出现的最好办法。

I've looked across this forum, and I've googled this one, and I'm not sure what is the best way to handle Javadoc and annotations that appear together in the same class.

从我可以从Sun / Oracle的文档看，他们似乎暗示（虽然我真的不能找到一个明确的说法）是应该的Javadoc注释上面列出。

From what I can see from Sun/Oracle's documentation, they seem to suggest (though I cannot really find an explicit statement) that Javadoc should be listed atop annotations.

看到自己的例子和如何当脱precate API的。

这是德precated或@覆盖的伟大工程，为一些简单的像@。可是你知道，如果你使用JPA和/或休眠？你的类和方法必然是相当多的沉重注解（每类或方法有时两个或两个以上的注解）。

That works great for something simple like @Deprecated or @Override. But what about if you use JPA and/or Hibernate? Your classes and methods are bound to be annotated quite a bit more heavily (sometimes two or more annotations per class or method).

我在注释顶部猜测的Javadoc还？

I'm guessing Javadoc still on top of annotations?

另外，我不知道应该如何最好地利用注解？我见过一些例子，在类，成员，方法顶部的注释堆栈。我也看到其他人在那里他们列出在同​​一行（通常是在此方法）的注释。

Also I wonder how should annotations best be used? I've seen some examples where the annotations "stack" on top of the class, member, method. And I've seen others where they list the annotations on the same line (usually a method here).

哪家最好？哪个更可读？

Which is best? Which is more readable?

和你的文件是事实，你你的Javadoc中注明的东西没有？

And do you "document" that fact that you annotated something within your Javadoc or not?

我正在寻找任何有关这一套好的文档和/或什么是最可读/可维护自己的经验。

I'm looking for either a good set of documentation about this and/or your own experience about what is most readable/maintainable.

推荐答案

的Javadoc只有在这里你的文档类，方法等注释可以改变给定的code的功能（如从休眠或Spring注解）的地方。所以，对我来说，很明显，注释应该是接近code（所以，Javadoc和方法/函数之间）。

Javadoc is only place where you document class, method, etc. Annotations can change functionality of given code (like annotations from Hibernate or Spring). So, for me, it is obvious that annotations should be closer to code (so, between javadoc and method/function).

但如何写注解，那里有很多人？这取决于我preFER离开他们在分开的线路，除了少数例外，如果有短，以某种方式连接。

But how to write annotations, where there is lot of them? It depends, I prefer to leave them in separated lines, with few exceptions if there are short and connected in some way.

在您使用注解的Javadoc明确文档化是不是一个好主意，我认为。注释可以有 @Documented 注解自己，其中规定，他们应该会出现在生成的javadoc。除了这一点，它是实现细节 - 的javadoc应该告诉什么方法/对象为做，你是不是如何这样做（主要是，至少）。

Explicit documenting in Javadoc that you are using annotations is not a good idea i think. Annotations can have @Documented annotations themselves, which states they should appear in generated javadocs. Beside this, it is implementation detail - javadoc should tell what method/object is made for, not how you are doing that (mostly, at least).

这篇关于什么是处理/格式的Javadoc和注释在code的最好方法？的文章就介绍到这了，希望我们推荐的答案对大家有所帮助，也希望大家多多支持IT屋！