14、开发综合要点与实践指南

开发综合要点与实践指南

1. Javadoc 规范

在代码编写中，为类的所有公共部分提供 Javadoc API 页面是必要的。Javadoc 工具与编译器共享大量代码，可用于生成这些页面。要创建 API 页面，需确保所有公共数据和方法都使用 Javadoc 风格的注释进行注释，然后对源代码运行 javadoc 命令。

1.1 基本使用

以下是一个没有 Javadoc 注释的类示例：

package xyz;
import java.util.*;
public class VectorOfStrings extends Vector<String> {
  public int  x;
  public int  y;
  public String toString() {
    return "Vector-o-Strings";
  }
}

要为这个类生成 API，可在命令行输入 javadoc VectorOfStrings.java ，会生成 13 个专业的 HTML 文件，包含索引、包概述和类页面。不过，类的整体描述以及字段、构造函数和方法的详细信息需程序员通过 Javadoc 注释提供。

1.2 Javadoc 注释格式

Javadoc 注释以 /** 开头，以 */ 结尾。类定义前的 Javadoc 注释会成为 API 页面中该类的描述，字段或方法前的注释则成为对应字段或方法的描述。例如添加了类描述