组织好代码段 以Java代码为例

1. 代码文件头部结构

   1. 版权和许可声明
   2. 命名空间(package)
   3. 外部依赖(import)

2. 对象结构

   1. 类的规范
   2. 类的声明
   3. 类的属性和方法

3. 类的内部结构

   1. 类的属性
   2. 构造方法
   3. 工厂方法
   4. 其他方法

4. 方法的代码结构

   1. 方法的规范
   2. 方法的声明
   3. 方法的实现

5. 限定词的使用 ----限定词推荐使用顺序：

   1. public/private/protected （访问控制限定词，制定访问权限）
   2. abstract （抽象类或者抽象方法，具体实现由子类完成）
   3. static （静态类、方法或者类属性）
   4. final （定义不能被修改的类、方法或者类属性）
   5. transient（定义不能被序列化的类属性）
   6. volatile（定义使用主内存的变量）
   7. default（声明缺省的方法）
   8. synchronized（声明同步的方法）
   9. native（声明本地的方法，也就是 Java 以外的语言实现的方法）
   10. strictfp（声明使用精确浮点运算）

6. 空行的使用

   1. 版权和许可声明代码块；
   2. 命名空间代码块；
   3. 外部依赖代码块
   4. 类的代码块；
   5. 类的属性与方法之间；
   6. 类的方法之间；
   7. 方法实现的信息块之间。

一个典型的规范，应该包含以下十个部分：

1. 方法的简短介绍；
2. 方法的详细介绍（可选项）；
3. 规范的注意事项 (使用 apiNote 标签，可选项)；
4. 实现方法的要求 (使用 implSpec 标签，可选项)；
5. 实现的注意事项 (使用 implNote 标签，可选项)；
6. 方法参数的描述；
7. 返回值的描述；
8. 抛出异常的描述：需要注意的是，抛出异常的描述部分，不仅要描述检查型异常，还要描述运行时异常；
9. 参考接口索引（可选项）；
10. 创始版本（可选项）。