私有/受保护方法的 JavaDoc？

JavaDoc for private / protected methods?

提问by smartmouse

Should I write JavaDoc for privateor protectedmethods? And what about privatevariables?

我应该为私有方法还是受保护方法编写 JavaDoc ？那么私有变量呢？

I see class examples on my Java book and the privatevariables are JavaDoc'ed. So I can't understand if it is a good practice to JavaDoc the private(or protected) methods.

我在我的 Java 书中看到了类示例，私有变量是 JavaDoc 的。所以我无法理解 JavaDoc私有（或受保护）方法是否是一个好习惯。

回答by Peter Bratton

You don't have to javadoc anything, but it's very helpful to. More javadocs are never a bad thing.

你不必 javadoc 任何东西，但它非常有帮助。更多的 javadoc 从来都不是坏事。

Per your question, if you use the javadoc documentation compiler, javadocs will be compiled for protected methods, but not private methods. There's no reason they can't still be used as code comments, though.

根据您的问题，如果您使用 javadoc 文档编译器，则会为受保护的方法而不是私有方法编译 javadoc。不过，没有理由不能将它们仍然用作代码注释。

回答by Josh M

Nope, you shouldn't write javadoc for private methods. End users don't have access to private fields or methods so there really isn't a point in providing javadoc for them. Private fields and methods are only meant for the developer. If you really need to though, feel free to write comments for non-obvious logic. You should probably write javadoc for protectedmethods because these methods are sometimes overridden and it is helpful to provide the user with some information about what the method does, or, should do.

不，您不应该为私有方法编写 javadoc。最终用户无权访问私有字段或方法，因此为他们提供 javadoc 确实没有意义。私有字段和方法仅适用于开发人员。如果您确实需要，请随时为不明显的逻辑写评论。您可能应该为protected方法编写 javadoc，因为这些方法有时会被覆盖，并且向用户提供有关该方法做什么或应该做什么的一些信息是有帮助的。

回答by AlexWien

Yes you should write JavaDoc for private methods, and even when it is only for yourself. In 3 years when you have to change the code, you will be happy that you documented it.

是的，您应该为私有方法编写 JavaDoc，即使它仅用于您自己。3 年后，当您必须更改代码时，您会很高兴自己记录下来。

If you leave the company, or have to work on another project, your co-workers will be happy to have a documented code. Undocumented code has much lower value.

如果你离开公司，或者不得不从事另一个项目，你的同事会很高兴有一个文档化的代码。未记录的代码的价值要低得多。

And look how the real professionals do it. Here is an excerpt from the source code of ArrayListclass by Sun Microsystems:

看看真正的专业人士是如何做到的。以下是Sun Microsystems ArrayList类源代码的摘录：

 /**
  * The array buffer into which the elements of the ArrayList are stored.
  * The capacity of the ArrayList is the length of this array buffer.
  */
  private transient Object[] elementData;

回答by ashes999

The first question you need to ask yourself is "why write JavaDocs at all?" Who are they useful for? Who asked you to write them?

您需要问自己的第一个问题是“为什么要编写 JavaDocs？” 它们对谁有用？谁让你写的？

Most likely, someone (employer / professor) asked you to document some of your methods. This is generally A Good Thing, but comes with a cost: additional maintenance.

最有可能的是，有人（雇主/教授）要求您记录您的一些方法。这通常是一件好事，但需要付出代价：额外的维护。

If you have a publicly accessible version of your docs (such as if you're generating them and publishing them online for end-users), it makes sense to document anything your end users will need to know.This includes all public classes and methods.

如果您有可公开访问的文档版本（例如，如果您正在生成它们并为最终用户在线发布它们），则记录您的最终用户需要知道的任何内容是有意义的。这包括所有公共类和方法。

What about for yourself, and other developers?

对于您自己和其他开发人员呢？

My opinion is that you shouldn't use javadocs on internal and private methods and classes.The main reason is that javadocs primarily benefit people who consume, not maintain, your code.

我的观点是你不应该在内部和私有方法和类上使用 javadoc。主要原因是 javadoc 主要使使用而不是维护您的代码的人受益。

On the other hand, you do need to keep notes and comments on your own code, which is often internal. In this case, I would suggest normal comments (eg. //) instead; it's less maintenance, and often, equally clear, with a lot less typing.

另一方面，您确实需要对自己的代码进行注释和注释，这通常是内部的。在这种情况下，我会建议正常评论（例如//）；它的维护更少，而且通常同样清晰，打字也少得多。

On the other hand, if a method becomes public, it can be useful to convert those comments into a true javadocs. Javadocs have the benefit of forcing you to think about (and document) every parameter, exception, and return value.

另一方面，如果一个方法成为公开的，那么将这些注释转换为真正的 javadocs 会很有用。Javadocs 的好处是迫使您考虑（并记录）每个参数、异常和返回值。

The trade-off is yours to make.

权衡是你的。

回答by Marco13

You often hear the general recommendation that, in the best case, comments should simply not be necessaryat all. But concerning JavaDoc, they play an important role not only for the developer, but also for the user of the library.

经常听人说，在最好的情况下，意见应干脆不一般建议有必要在所有。但是对于 JavaDoc，它们不仅对开发人员而且对库的用户都起着重要的作用。

Additionally, writing JavaDoc comments may be more useful for you (especially for a beginner) than for anyone else: When you find it hard to describe what a variable is or what a method does with a single /** One-line-JavaDoc comment */, then you'll automatically re-think what you have done there.

此外，编写 JavaDoc 注释可能对您（尤其是初学者）比对其他人更有用：当您发现难以描述变量是什么或方法对单个/** One-line-JavaDoc comment */.你在那里做了什么。

When generating JavaDocs, you may choose whether you want to generate them only for the publicand protectedparts of the API, or also for default- or privateelements.

生成 JavaDoc 时，您可以选择是仅为API的public和protected部分生成它们，还是还为默认或private元素生成它们。

However, you should in any case document protectedmethods: May someone who extends the class only callthis method, or is he also allowed to override this method? If so, are there any pre- and postconditions that he should know about? Should he call super.theMethod()in the overridden version? (BTW: If he's not allowed to override the method, then it should be final, but documented anyhow)

但是，无论如何，您都应该记录protected方法：扩展类的人可以只调用此方法，还是也允许他覆盖此方法？如果是这样，是否有任何他应该知道的先决条件和后继条件？他应该调用super.theMethod()被覆盖的版本吗？（顺便说一句：如果他不允许覆盖该方法，那么它应该是final，但无论如何都要记录）

BTW: I personally comment everything, but know that most people think it's not necessary or even a bad style, especially for "trivial" things

BTW：我个人评论一切，但知道大多数人认为没有必要甚至是一种糟糕的风格，尤其是对于“琐碎”的事情

/**
 * The number of elements in this set
 */
private final int numberOfElements;

I think it does not harm, but helps in many cases. Maybe, regarding privateparts, it's just a matter of taste.

我认为它不会造成伤害，但在许多情况下会有所帮助。也许，关于private零件，这只是品味问题。