JavaDoc for private / protected methods？[已关闭]

java private protected javadoc

2022-08-31 17:08:35

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

我在我的Java书上看到类示例，私有变量是JavaDoc的。所以我不明白JavaDoc私有（或受保护）方法是否是一种好的做法。

答案 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;

答案 2

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

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

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

那么你自己和其他开发人员呢？

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

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

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

权衡取舍由您自己决定。