第八十二条：将线程安全性写在文档中

 当并发使用一个类的方法时，类的行为方式是该类与其客户端建立的约定的重要组成部分。如果这方面的内容你没有在类的文档中记录下来，使用这个类的用户将被迫做出假设。如果这些假设是错误的，这样得到的程序就可能缺少足够的同步（第78项）或者过度同步（第79项）。无论哪种情况，都可能导致严重的错误。

  你可能听到过这样的说法：通过查看文档中是否出现synchronized修饰符，你可以确定一个方法是否是线程安全的。这种说法从几个方面来说都是错误的。在正常的操作中，Javadoc并没有在它的输出中包含synchronized修饰符，是有好的理由的。因为在一个方法中出现synchronized修饰符，这是个实现细节，并不是API的一部分 。它并不一定表明这个方法是线程安全的。

  而且，“使用synchronized修饰符声明的存在就足以用文档说明线程的安全性”的这种说法说体现了一种误解，即线程安全是全有或全无的属性。实际上，线程安全性有多种级别。一个类为了可以被多个线程安全地使用，必须在文档中清楚地说明它所支持的线程安全性级别 。下面的列表概括了线程安全性的几种级别。这份列表并没有涵盖所有的可能，而只是些常见的情形：

• 不可变的（immutable）——这个类的实例视不变的。所以，不需要外部的同步。这样的例子包括String、Long和BigInteger。
• 无条件的线程安全（unconditionally thread-safe）——这个类的实例是可变的，但是这个类有足够的内部同步，所以，它的实例可以被并发使用，无需任何外部同步。其