用于私有/受保护方法的 JavaDoc？ [关闭]

Posted 2023-02-25

【中文标题】用于私有/受保护方法的 JavaDoc？ [关闭]

【英文标题】：JavaDoc for private / protected methods? [closed]

【发布时间】：2014-03-05 02:54:06

【问题描述】：

我应该为 private 还是 protected 方法编写 JavaDoc？那么私有变量呢？

我在我的 Java 书上看到了类示例，并且 private 变量是 JavaDoc 的。 所以我不明白JavaDoc private（或protected）方法是否是一个好习惯。

【问题讨论】：

你应该为任何不明显的东西写 cmets。

如果您在 IDE（至少是 Intellij）中使用 show javadocs 命令，您的私有/受保护方法的 javadocs 中将显示。在线 cmets 不会。当方法签名之外的描述有用时，这是 javadocs 而不是内联 cmets 的一个实际好处。

【参考方案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;

【讨论】：

public HelloWorld() system.out.println("Hello World") 的价值是否小于 //prints Hello World HelloWorld() system.out.println("Hello World") ?

我们不谈论一个众所周知的Hello world coede。在专业开发中，未经处理的代码会导致下一个处理该代码的人的成本更高。即使它是你自己的代码，在创建几年后，你会花更多的时间思考为什么和什么，而不是在创建时记录成本。

这个问题显然是关于 JAVADOC 的。正如ashes999 的回答所说，Javadoc 主要面向使用您的代码的人。您正在谈论评论您的代码并且您所说的是有效的，我在同一条路径上，但这并不适用于 javadoc。 Javadoc 的设计目的不是为您自己和您的同事保留您的 cmets，并为您的所有消费者公开它们。

@testuser 对您的评论：“javadoc 并非旨在保留您的 cmets...” Javadoc 有一个功能，它允许您仅为公共方法/字段创建 javadoc html。因此，如果有必要隐藏信息，请为自己编写私人信息，并仅为消费者发布公共信息。

@AlexWien：这是一个有效的观点，但是使它成为 Javadoc cmets 有什么好处呢？为什么不简单地将其保持为“简单”的 cmets？ Javadoc 恕我直言（有点，但仍然）更多的工作。并且只生成公共 HTML 的一部分，我想它需要一些额外的配置，因此会花费额外的时间，而您可以简单地将其添加为“普通”cmets。

【参考方案2】：

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

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

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

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

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

另一方面，您确实需要在自己的代码上保留注释和 cmets，这通常是内部代码。在这种情况下，我会建议使用普通的 cmets（例如//）；它的维护工作更少，而且通常同样清晰，打字也少很多。

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

权衡取舍由您决定。

【讨论】：

仅供参考，对于 .NET 开发人员，当您将鼠标悬停在方法名称上时，Visual Studio 会显示这些 cmets——即使对于私有方法也是如此——因此对于 .NET 代码，这样做是有意义的。

Eclipse 也是如此，这是一个非常有益的功能。

我不明白为什么“//”比“/**”的维护更少。并且实际上使用“//”更多的是打字，因为eclipse会自动为你生成javadoc tremplate。

AFAIK eclipse、visual studio、netbeans 和 intellij 可以非常方便地显示 javadoc，所以在我看来，这对使用您的代码的每个人都有好处。

@kidburla 我会为protected 方法编写javadoc cmets，因为当这些方法被覆盖时，它们将被继承。而且，如果您正在开发其他开发人员将在其上构建的平台应用程序，则可以节省重写 java doc cmets。如果被覆盖的方法行为发生变化并将被公开使用，那么他们将需要编写 javadoc cmets 的修订版本。

【参考方案3】：

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

【讨论】：

那么变量呢？

您不应该使用 javadoc 私有字段，但欢迎您使用 javadoc protected 字段，因为它们通常对于为什么它们是 protected 而不是 private 具有一定的意义。您仍然可以在任何地方提供注释行，无论是描述变量的用途还是方法中的逻辑。

如果你为私有方法或字段提供注释行，你最好写一个javadoc，这没有缺点，只有优点。

@AlexWien 我不同意您的回答，但是为私人成员编写 javadoc 而不是 cmets 的目的是什么？成员是私有的，以防止用户直接访问它（尽管有反射）。如果你是 javadoc 私有成员，你不是让最终用户更容易对程序进行逆向工程吗？

编写 javadoc 并不意味着将其呈现给最终用户。私有方法的 javadoc 给出了如何（内部）评论的结构。它要求注释所有参数和返回值。这是一个快速模板，可加快您的文档编制时间。为了保护逆向工程，您必须混淆并保留公共接口。进一步的日食显示了一个很好的鼠标弹出文档的（私有）方法，它是 javadoced

【参考方案4】：

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

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

在生成 JavaDocs 时，您可以选择是否只为 API 的 public 和 protected 部分生成它们，或者也为默认或 private 元素生成它们。

但是，无论如何，您都应该记录protected 方法：扩展类的人只能调用这个方法，还是允许他重写这个方法？如果是这样，是否有任何他应该知道的前置条件和后置条件？他应该在覆盖的版本中调用super.theMethod() 吗？ （顺便说一句：如果不允许他重写该方法，那么它应该是final，但无论如何都记录在案）

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

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

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

【参考方案5】：

您不需要 javadoc 任何东西，但它非常有帮助。更多的 javadocs 从来都不是一件坏事。

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