java - 如何将 javadoc 添加到 Java 中的静态初始化程序？

Question

我重构了一个类，并将一些代码从构造函数移到了静态初始化程序。我应该如何处理构造函数上的 javadoc？是否可以将 javadoc 添加到静态初始化程序？

score 8 · Accepted Answer

JavaDoc 主要用于记录类的接口。JavaDoc 注释必须在类、字段、构造函数或方法声明之前。

静态初始化器不是接口的一部分。它是类实现的一部分。

如果需要，您可以在类文档中记录其行为。

score 8 · Accepted Answer

首先也是最重要的，静态初始化器是否是开始的好习惯是有争议的。

如果您仍然决定使用它们，我会在类级别将文档添加到 JavaDoc 中。静态初始化器可能会产生副作用，具体取决于它们的实现方式。如果您使用具有副作用的静态初始化程序，则应为该类的使用者记录该行为。

score 2 · Accepted Answer

Java 中没有静态构造函数（相对于 C#），这就是为什么您必须在类级别记录此行为的原因。

此外，由于静态初始化器很可能会初始化一些静态字段，如果这些字段是公共的、受保护的（或包私有的，取决于您的 JavaDoc 可见性约定），您应该添加有关这些字段初始化方式的详细信息静态初始化器的行为。

score 2 · Accepted Answer

我想说该文档的重要部分应该移到类的文档中：

/**
 * Your text here.
 */
public class SomeClass {
   static {
      /* your static initalizer */
   }
}

4 回答 4