简体繁体 English

Java中应该有什么javadoc？

[英]What should have javadoc in Java?

原文 2010-10-15 02:16:42 5 3 java/ javadoc/ conventions

What should be documented by javadoc comments (classes, methods, constructors and fields? Or only classes methods and constructors?)? 应该通过javadoc注释（类，方法，构造函数和字段？或者只有类方法和构造函数？）来记录什么？ Is there any convention about that ? 那有什么约定吗？

Please provide links to relevant resources in your answer whenever possible. 请尽可能在答案中提供相关资源的链接。 Thank you 谢谢

EDIT: The question is not about how is it usualy done or what is logical to comment with javadoc. 编辑：问题不在于如何通过javadoc进行评论或使用javadoc进行评论是合乎逻辑的。 The question is what can be found about this matter in any official Sun/Oracle documents (guidelines about writing javadoc, conventions, specifications and so on). 问题是在任何官方Sun / Oracle文档中可以找到关于此事的内容（关于编写javadoc，约定，规范等的指南）。 Also please do not answer about how should the javadoc comments look like, the question is specifically about what should be commented, not how. 另外请不要回答有关javadoc评论应该如何的问题，问题是关于应该评论什么，而不是如何评论。

3 个解决方案

Javadoc is to document the public API of your code. Javadoc用于记录代码的公共API。

In a nutshell, you need to document all your public and protected classes, methods, constructors, and fields (because they are accessible to your users). 简而言之，您需要记录所有公共和受保护的类，方法，构造函数和字段（因为用户可以访问它们）。

You need to describe what a method does, not how it does it. 您需要描述方法的作用，而不是它是如何做的。 Of course, if implementation details result in interesting side-effects, for example performance characteristics, and also usage limitations, those should be mentioned. 当然，如果实现细节导致有趣的副作用，例如性能特征以及使用限制，那么应该提及这些副作用。

Oracle has official guidelines on " How to Write Doc Comments for the Javadoc Tool ". Oracle有关于“ 如何为Javadoc工具编写Doc注释 ”的官方指南。

Simple and general rules for javadoc as mentioned by Thilo and also from here should be as follows : Thilo提到的javadoc的简单和一般规则以及此处应该如下：

Javadoc Guidelines Javadoc指南

General Rules 通用规则

All public and protected methods must have full documentation 所有公共和受保护的方法都必须有完整的文档

Trivial getters and setters are exempted from this rule. 琐碎的getter和setter免于此规则。 Doing 干
anything but returning or changing a 什么，但返回或改变一个
variable in a getter or setter should be documented. 应记录getter或setter中的变量。

Private methods with non-obvious implementations should have enough 具有非显而易见的实现的私有方法应该足够了
documentation to allow other 允许其他的文档
developers to debug them 开发人员调试它们

Official guidelines are found here : How to Write Doc Comments for the Javadoc Tool 官方指南可在此处找到：如何为Javadoc工具编写Doc注释

Imagine showing the code to someone else who is familiar with the programming language, but not your project. 想象一下，将代码展示给熟悉编程语言的其他人，而不是您的项目。 Whichever parts you feel the need to explain as you're watching him review it should be documented. 无论您认为需要解释哪个部分，因为您正在观看他的评论，应该记录下来。

similar question on programmers.SE: Should you document everything or just most? 关于程序员的类似问题.SE：你应该记录一切还是只记录大部分内容？