在代码中处理/格式化 Javadoc 和注释的最佳方法是什么? [英] 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.

查看他们的示例如何以及何时弃用 API.

这对于像@Deprecated 或@Override 这样简单的事情非常有用.但是如果你使用 JPA 和/或 Hibernate 呢?您的类和方法肯定会被大量注释(有时每个类或方法有两个或多个注释).

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 只是记录类、方法等的地方.注解可以改变给定代码的功能(如来自 Hibernate 或 Spring 的注解).所以，对我来说，很明显注解应该更接近代码(所以，在 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).

但是怎么写注解，哪里有很多注解?视情况而定，我更喜欢将它们分开放置，如果有短线并以某种方式连接，则很少有例外.

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 和注释的最佳方法是什么?的文章就介绍到这了，希望我们推荐的答案对大家有所帮助，也希望大家多多支持IT屋！