Question

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

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

Answer 1

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

如果您离开公司，或者必须在另一个项目上工作，您的同事将很乐意拥有一份记录在案的代码。未记录的代码的价值要低得多。

看看真正的专业人士是如何做到的。以下是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;

Answer 2

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

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

如果您拥有可公开访问的文档版本（例如，如果您要生成这些文档并在线发布给最终用户），那么记录您的最终用户需要了解的内容是有意义的。< / em>这包括所有公共类和方法。

为自己和其他开发者做些什么？

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

另一方面，您需要在自己的代码上保留注释和注释，这通常是内部代码。在这种情况下，我会建议正常的评论（例如//）;它的维护较少，而且往往同样清晰，打字少得多。

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

需要权衡利弊。

Answer 3

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

Answer 4

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

此外，编写JavaDoc注释可能对您（尤其是初学者）比对其他任何人更有用：当您发现难以描述变量是什么或方法对单个/** One-line-JavaDoc comment */的作用时，然后你会自动重新思考你在那里做了什么。

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

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

BTW：我个人评论所有，但要知道大多数人认为这不是必要的，甚至是不好的风格，特别是对于“琐碎”的事情

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

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

Answer 5

你不需要任何javadoc，但它非常有帮助。更多javadocs绝不是坏事。

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

私有/受保护方法的JavaDoc？

5 个答案: