JAVA注释及说明的一些总结

JAVA中需要对类、方法、测试等进行说明，一份完整的说明包括AF、RI、rep exposure、specification，test strategy、thread safety等，在这里进行总结：

1. AF
   AF是Abstraction Function(抽象函数)的简称，它在我们设计ADT时用到，它映射了我们实现时用到的值空间到类需要支持的值空间。简单来说，就是我们是如何在自己的类中使用一些数据结构来表示这个类需要表示的对象的。比如，需要一个设计一个字符集合ADT，我们选择使用一个字符串来实现。那么这个映射关系如下：
   
   可以看到，这个映射是一个满射，但不一定是单射，因为"abc"，“acb"这两个实现都同时映射到了{a,b,c}这一个集合。此外，还有一些不能映射的实现，比如说"aa”，因为集合不能有两个相同的元素。于是，我们需要在类的头部，类属性后进行如下说明：
   
2. RI
   RI是Rep Invariant(表示不变量)的简称，它是一个从AF里所叙述的R空间到Boolean的映射。简单来说，就是如何判断根据你设计的这个类创建的某些对象，是否能表示需要表示的真实的对象。以上面的图举例，字符串"acb"能表示真实的对象，也就是{a,b,c}集合，但是"aa"不能，因为集合不能包含两个相同元素，从而"acb"映射到了true，"aa"映射到了false，表示创建了一个错误的对象。同样，我们在类属性后进行如下说明：
   
   如果我们需要避免创建错误对象情况的发生，就需要在程序发布之前的版本中写入private void checkRep()方法，这个方法在构造函数以及改变了对象结构的方法中末尾调用，及时排除那些错误的对象，并抛出异常提示我们。

    Set<Character> chars = new HashSet<Character>();
    for(int i = 0;i < s.length();i++) {
      char c = s.charAt(i);
      assert !chars.contains(c);
      chars.add(c);
    }

3. Safety from Rep Exposure
   即防止表示泄露策略，描述自己使用了什么策略来防止这个类的属性被外部随意调用、更改的。举例来说，如果一个类中使用了Set集合，并且允许这个类以外的类随意调用（不管是通过对象直接获取，还是通过get方法获取），那么这个集合的引用就被暴露了，集合中的内容可能在程序中你意想不到的地方被秘密地更改，甚至改变引用指向的具体内容，因此会出现潜在的逻辑错误。为了避免，我们只允许通过如下方式调用这个集合属性：

class Test {
  private final Set<String> set;
  public Set<String> getSet(){
    return new HashSet<String>(set);
  }
}

我们将属性设置为最终私有，并且在get方法中复制一个新的集合返回，这样即使被外界修改，也无法影响到这个对象。于是，我们紧接着RI，在底下继续写道：

//Safety from Rep Exposure:
//   set is final, and has made defensive copies to avoid sharing the rep with client.

4. specification
   方法的规格说明，在方法头部注明，包含方法的内容，前置条件，后置条件，参数说明，返回值说明，异常说明，举例如下：

  /**
   * Set the element of the char set.
   * 
   * @param s char set in the form of a string, should not contain repeated chars
   * @return true if the set is changed; otherwise false
   * @throws Exception if the string has illegal char
   * 
   */
  public boolean setString(String s) {
  }

5. test strategy
   测试策略，在编写测试样例时需要对测试样例进行分区，由于测试的元素不止一个，需要按照笛卡尔乘积对每一个等价情况编写一个测试样例，需要在测试类头部说明测试策略，即有哪些区域需要覆盖，而在测试方法头部写明该方法覆盖了哪些区域。例如，我们编写了一个翻转字符串末尾指定位数字符的方法，需要写明：
   以及
   
6. thread safety
   线程安全策略，同样写在类头部，写明这个类是如何保证线程安全的除上述声明外，还有使用了同步技术等其他方式，当然这又是另一话题了，这里不再赘述。

总结一下，需要说明的有：
在类头部：抽象函数、表示不变量、防表示泄露策略、线程安全策略（如果有线程的话）
在方法头部：规格说明
在测试类头部：测试样例需要覆盖的分区
在测试方法头部：测试样例覆盖的分区