Java 注释约定
声明：本页面是StackOverFlow热门问题的中英对照翻译，遵循CC BY-SA 4.0协议，如果您需要使用它，必须同样遵循CC BY-SA许可，注明原文地址和作者信息，同时你必须将它归于原作者（不是我）：StackOverFlow
原文地址: http://stackoverflow.com/questions/3593309/
Warning: these are provided under cc-by-sa 4.0 license. You are free to use/share it, But you must attribute it to the original authors (not me):
StackOverFlow
Java Commenting Conventions
提问by Garee
Which method of commenting is most widely accepted or does it really matter?
哪种评论方法最被广泛接受或者它真的很重要？
I have been using
我一直在使用
/**
* (Method description)
* @param
* @return
* etc
*/
However I have read of:
但是我读过：
Precondition:
Postcondition:
Is there a more 'professional' way of commenting?
有没有更“专业”的评论方式？
回答by Gunslinger47
Here are the Java coding conventions for comments recommended by Oracle:
以下是 Oracle 推荐的注释的 Java 编码约定：
Here are Google's recommendations for their Android platform:
以下是 Google 对其 Android 平台的建议：
For more detailed information on style and conventions for Javadoc, see here:
有关 Javadoc 样式和约定的更多详细信息，请参见此处：
回答by Arnold Spence
The comment style in your first example is not just a convention, it is a standard for a documentation tool called Javadoc. If you follow that Javadoc commenting style, you will be able to easily generate html formatted documentation for all of your source code.
第一个示例中的注释样式不仅仅是一种约定，它还是名为Javadoc的文档工具的标准。如果您遵循 Javadoc 注释风格，您将能够轻松地为您的所有源代码生成 html 格式的文档。
回答by YoK
I would simply follow standard defined by Sun (Oracle) for writing Javadoc. Javadoc is referred by all developers unanimously :). For more information click here
我会简单地遵循 Sun (Oracle) 定义的标准来编写 Javadoc。Javadoc 被所有开发人员一致引用:)。欲了解更多信息，请单击此处
I would also ask you to do following search on Stackoverflowfor lots of questions and ansers on commenting.
我还会请您在 Stackoverflow 上进行以下搜索，以获取有关评论的大量问题和答案。
回答by Nitesh Verma
回答by Siddh
First off all having readable code and readable comments are two things that are totally different.
首先，可读代码和可读注释是完全不同的两件事。
Readable code is code the uses good variable, method, class names, etc.
可读代码是使用好的变量、方法、类名等的代码。
Readable comments are more a matter of personal taste. Some people like comments to follow grammatical rules that would be used to write a book while others couldn't care less about grammatical stuff. You can go through this link:
可读的评论更多的是个人品味的问题。有些人喜欢评论遵循用于写书的语法规则，而另一些人则不太关心语法内容。你可以通过这个链接：
http://www.oracle.com/technetwork/java/codeconventions-141999.html#385
http://www.oracle.com/technetwork/java/codeconventions-141999.html#385
From readable code and comments, you can create documentation with the help of doxygen.
从可读的代码和注释，您可以在 doxygen 的帮助下创建文档。
