私有/受保护方法的JavaDoc？

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

我在Java书上看到了类示例，私有变量是JavaDoc'ed。

---

因此，我不明白JavaDoc私有（或受保护）方法是否是一种好的实践。

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

---

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

不，您不应该为私有方法编写javadoc。最终用户没有访问私有字段或方法的权限，所以为他们提供javadoc是没有意义的。私有字段和方法仅适用于开发人员。如果你真的需要的话，可以随意写一些非明显逻辑的评论。您可能应该为受保护的方法编写javadoc，因为这些方法有时会被重写，向用户提供有关该方法的功能或应该功能的一些信息是很有帮助的

是的，您应该为私有方法编写JavaDoc，即使它只是为您自己编写的。在3年内，当你不得不更改代码时，你会很高兴你记录了它

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

看看真正的专业人士是怎么做的。以下是ArrayList类源代码的摘录：

---

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

很可能是有人（雇主/教授）让你记录你的一些方法。这通常是一件好事，但也有成本：额外的维护

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

对于你自己和其他开发者来说呢

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

另一方面，您确实需要对自己的代码（通常是内部代码）保留注释和注释。在这种情况下，我建议使用普通的注释（例如

/

）；它的维护更少，而且通常同样清晰，只需输入更少的内容

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

---

权衡取舍是你自己的事。

你经常听到这样的一般性建议：在最好的情况下，评论根本不需要。但是关于JavaDoc，它们不仅对开发人员，而且对库的用户都起着重要的作用

此外，编写JavaDoc注释可能对您（尤其是初学者）比其他任何人都更有用：当您发现很难用一行JavaDoc注释来描述变量是什么或方法做了什么时，您会自动重新思考您在那里做了什么

在生成Javadoc时，您可以选择是仅为API的

公共

和

受保护

部分生成Javadoc，还是为默认或

私有

元素生成Javadoc

但是，在任何情况下都应该记录受保护的方法：扩展类的人可以只调用此方法，还是也可以重写此方法？如果是的话，他是否应该知道任何前后条件？他是否应该在重写版本中调用

super.theMethod（）

？（顺便说一句：如果不允许他重写该方法，那么它应该是

最终的

，但无论如何都要记录在案）

顺便说一句：我个人对每件事都发表评论，但我知道大多数人认为这不是必要的，甚至是一种糟糕的风格，尤其是对于“琐碎”的事情

---

我认为这没有害处，但在很多情况下是有帮助的。也许，关于

private

部分，这只是一个品味问题。

您应该为任何不明显的内容编写注释。在您的Javadoc中，如果您在IDE中使用show javadocs命令（至少Intellij），则会显示私有/受保护方法。在线评论将不会出现。当方法签名之外的描述很有用时，这是javadocs代替内联注释的一个实际好处。那么变量呢？您不应该使用javadoc私有字段，但是欢迎您使用javadoc

protected

字段，因为它们通常对它们受

保护的原因有一定的意义，而不是
private
。您仍然可以在任何地方提供注释行，无论它是描述变量的用途还是方法中的逻辑。如果您为私有方法或字段提供注释行，您最好编写一个javadoc，这没有缺点，只有建议。@AlexWien我不同意您的回答，但是，为私人成员编写javadoc而不是注释的目的是什么呢？成员是私有的，以防止用户直接访问它（尽管存在反射）。如果您是javadoc私有成员，您是否让最终用户更容易对程序进行反向工程？编写javadoc并不意味着向最终用户展示它。私有方法的javadoc提供了一个如何（内部）注释的结构。它要求注释所有参数和返回值。这是一个快速模板，加快了您的文档记录时间。为了保护逆向工程，你必须混淆，并让公众
 /**
  * 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;

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