手写 List 容器的源码注释规范

为提升代码可读性与维护性，遵循以下注释规范（以伪代码形式展示核心逻辑）：

1. 文件头部注释

说明文件职责、核心设计思想及版本信息：

/**
 * 自定义动态数组实现 (ArrayList 变体)
 * 核心特性：
 *   - 自动扩容机制：容量不足时按 $newSize = oldSize \times 1.5$ 增长
 *   - 支持泛型存储
 *   - 线程不安全设计
 * 
 * 版本记录：
 *   1.0 (2023-10-01) 初始版本
 *   1.1 (2023-11-15) 优化迭代器失效处理
 */

2. 类成员注释

清晰标注每个成员变量的作用：

public class MyList<T> {
    // 底层数据存储数组，初始容量为10
    private T[] elementData;
    
    // 当前实际元素数量（非数组长度）
    private int size = 0;  
    
    // 修改计数器，用于快速失败(fail-fast)迭代检测
    private int modCount = 0;  
}

3. 方法注释规范

(1) 公共方法：说明功能、参数、返回值及边界条件

/**
 * 在指定索引处插入元素
 * 
 * @param index 插入位置 (需满足 $0 \leq index \leq size$)
 * @param element 待插入元素
 * @throws IndexOutOfBoundsException 当 $index < 0$ 或 $index > size$ 时抛出
 * 
 * 时间复杂度：$O(n)$ (需移动后续元素)
 */
public void add(int index, T element) {
    rangeCheckForAdd(index);  // 边界校验
    ensureCapacity(size + 1); // 容量检查
    System.arraycopy(elementData, index, elementData, index+1, size-index);
    elementData[index] = element;
    size++;
    modCount++;
}

(2) 私有方法：解释实现细节

// 执行扩容操作：当所需容量 > 当前数组长度时触发
private void grow(int minCapacity) {
    int oldCapacity = elementData.length;
    // 新容量 = max(旧容量*1.5, 最小需求容量)
    int newCapacity = oldCapacity + (oldCapacity >> 1); 
    if (newCapacity < minCapacity) {
        newCapacity = minCapacity;
    }
    elementData = Arrays.copyOf(elementData, newCapacity);
}

4. 关键算法注释

复杂逻辑需添加行内说明：

// 快速排序实现 (用于sort方法)
private void quickSort(int left, int right) {
    if (left < right) {
        int pivotIndex = partition(left, right); // 获取基准点
        quickSort(left, pivotIndex - 1);  // 递归左区间
        quickSort(pivotIndex + 1, right); // 递归右区间
    }
}

5. 异常处理注释

明确异常触发条件：

/**
 * 获取指定位置的元素
 * 
 * @throws IndexOutOfBoundsException 当 $index < 0$ 或 $index \geq size$ 时抛出
 */
public T get(int index) {
    if (index < 0 || index >= size) {
        // 明确异常信息包含边界值
        throw new IndexOutOfBoundsException(
            "Index: " + index + ", Size: " + size
        );
    }
    return elementData[index];
}

6. 维护性标记

使用标准标签标注待优化点：

// TODO: 当前扩容策略可能产生内存碎片，未来考虑内存池优化
// NOTE: 迭代器实现依赖modCount，修改数据结构时需同步更新

注释原则总结

1. 必要性：避免冗余注释（如i++ // 增加i），只解释非显然逻辑
2. 实时性：代码修改时同步更新注释
3. 一致性：团队统一使用/** Javadoc */或//风格
4. 可追溯性：关键变更添加版本标记（如// Modified in v1.2）

通过规范注释，可使容器实现具备：

• 可读性：新人快速理解设计思路
• 可维护性：修改时明确影响范围
• 可扩展性：标注潜在优化点引导后续开发