类与main方法的JavaDoc编写差异及规范咨询

你当前的写法是不正确的——把类和main方法的JavaDoc混在同一段里，既没明确类的核心职责，又重复了内容，不符合JavaDoc的编写规范。正确的做法是分开编写，各自聚焦自身的职责：

类的JavaDoc #

聚焦说明类的核心定位与整体功能，不用提及main方法的具体执行逻辑，只需要讲这个类能提供什么能力：

/**
 * 提供double数组的最小值、最大值、平均值计算功能的工具类
 */
public class ArrayStats {
    // 方法实现...
}

main方法的JavaDoc #

聚焦说明这个方法的具体作用——也就是它作为程序入口，实际会做什么：

/**
 * 程序入口方法：定义测试用的double数组，调用本类的统计方法，打印数组的最小值、最大值与平均值
 */
public static void main(String[] args) {
    // 方法实现...
}

完整示例 #

/**
 * 提供double数组的最小值、最大值、平均值计算功能的工具类
 */
public class ArrayStats {

    /**
     * 计算给定double数组的最小值
     * @param arr 待计算的double数组，不能为空
     * @return 数组中的最小值
     */
    public static double minValue(double[] arr) {
        // 实现逻辑
        double min = arr[0];
        for (double num : arr) {
            if (num < min) min = num;
        }
        return min;
    }

    /**
     * 计算给定double数组的最大值
     * @param arr 待计算的double数组，不能为空
     * @return 数组中的最大值
     */
    public static double maxValue(double[] arr) {
        // 实现逻辑
        double max = arr[0];
        for (double num : arr) {
            if (num > max) max = num;
        }
        return max;
    }

    /**
     * 计算给定double数组的平均值
     * @param arr 待计算的double数组，不能为空
     * @return 数组的平均值
     */
    public static double averageValue(double[] arr) {
        // 实现逻辑
        double sum = 0;
        for (double num : arr) {
            sum += num;
        }
        return sum / arr.length;
    }

    /**
     * 程序入口方法：定义测试用的double数组，调用本类的统计方法，打印数组的最小值、最大值与平均值
     * @param args 命令行参数（未使用）
     */
    public static void main(String[] args) {
        double[] testArr = {1.2, 3.4, 5.6, 2.1};
        System.out.println("最小值：" + minValue(testArr));
        System.out.println("最大值：" + maxValue(testArr));
        System.out.println("平均值：" + averageValue(testArr));
    }
}

简单总结：类的JavaDoc讲“这个类是干什么的”，main方法的JavaDoc讲“这个方法具体做什么操作”，两者各司其职就不会出现内容重复的问题。

内容的提问来源于stack exchange，提问作者Gabi23