java集合框架源码注释是理解边界行为的权威依据，明确说明null允许性、异常条件及匹配逻辑等关键约定，如arraylist允许多个null，hashmap允null键值而treemap仅允null值，且包级文档规定null默认抛npe。

Java 集合框架的源码注释（尤其是 JDK 官方实现，如 ArrayList、HashMap、LinkedList）是理解边界行为最权威的一手资料。很多关键约定——比如是否允许 null、在什么位置允许、null 作为键或值时如何影响方法语义——并不总在 API 文档（Javadoc）正文里显式强调，而是在类/方法的注释块中以自然语言明确说明。

重点关注类级注释中的“Implementation Notes”和“Design Notes”

这些段落往往定义了整个集合的行为基调。例如：

• ArrayList 类注释明确写：“This class permits all elements, including null.” —— 表明它对 null 完全宽容，且不区分 null 是合法元素还是异常信号。
• HashMap 注释则分两处强调：“The HashMap class permits null values and the null key.” 和 “…but the Hashtable class does not.” —— 直接对比，点明设计选择，并暗示 null 键/值是其核心能力之一。
• TreeMap 注释警告：“…the map forbids null keys but permits null values.” —— 明确区分键与值的约束，根源在于比较逻辑（Comparable 或 Comparator 在遇到 null 时可能抛 NullPointerException）。

逐个查看关键方法的 Javadoc，注意“@param”和“@throws”之外的描述性句子

方法级注释常隐藏关键边界逻辑：

• get(int index) 在 ArrayList 中注明：“Returns the element at the specified position in this list. … If the index is out of range (index = size()), an IndexOutOfBoundsException is thrown.” —— 这里不仅说明异常类型，更给出了精确的边界表达式，比泛泛说“invalid index”更有指导性。
• put(K key, V value) 在 HashMap 中写：“If the map previously contained a mapping for the key, the old value is replaced… null values are permitted.” —— 暗示 put(null, null) 是合法操作，且会覆盖旧的 null 键映射。
• remove(Object o) 在 LinkedList 中强调：“Removes the first occurrence of the specified element from this list, if it is present. If this list does not contain the element, it is unchanged. More formally, removes the element with the lowest index i such that (o==null ? get(i)==null : o.equals(get(i)))…” —— 这段代码式描述直接揭示了 null 元素的匹配逻辑：用引用相等（==）判断 null，而非 equals，避免空指针。

结合实际调用链，验证注释与行为的一致性

读注释后，不妨快速翻看对应方法的源码（哪怕只看几行），确认注释未被过时或遗漏。例如：

• 看到 ConcurrentHashMap 注释说“Neither keys nor values are permitted to be null.”，就去查 putVal 方法开头——果然有 if (key == null || value == null) throw new NullPointerException();。
• 发现 Collections.unmodifiableList 返回的包装类，其 add 方法注释为“Always throws UnsupportedOperationException.”，再看源码实现，就是一行 throw new UnsupportedOperationException(); —— 注释与实现完全对齐，没有歧义。

留意包级文档（package-info.java）里的全局约定

像 java.util 包的 package-info.java 文件，开篇就声明：“…unless otherwise noted, passing a null argument to a constructor or method in any class or interface in this package will cause a NullPointerException to be thrown.” —— 这是一条默认铁律。所有例外（如 ArrayList 允许 null）都必须在具体类/方法注释中**主动声明**。因此，没看到明确许可，就默认不支持 null。