[Java 基础]Java 语言的规范

news2025/6/6 16:35:19

代码格式

缩进：代码的层次感

怎么做：统一使用 4 个空格进行缩进。不要用 Tab 键，因为不同的编辑器对 Tab 的显示宽度可能不一致，容易造成混乱。

大括号：清晰的代码块边界

风格：推荐使用 K&R 风格（Kernighan & Ritchie）：

左大括号 { 放在语句块的开始处，不另起一行，与前一个关键字或方法名在同一行，中间有一个空格。

右大括号 } 另起一行，与对应的左大括号对齐。

例外：对于空的代码块，可以直接写成 {}。

if (condition) {
    // 代码块
} else {
    // 代码块
}

public void doSomething() {
    // 方法体
}

行的长度：保持适中

建议：每行代码的长度尽量不要超过 120 个字符。

过长怎么办：如果一行代码过长，应该进行换行。换行时要保持适当的缩进，使代码逻辑清晰。通常在运算符、逗号后面或方法调用的点号 .处进行换行。

// 过长的代码行
String veryLongString = "This is a very long string that exceeds the recommended line length and needs to be broken down for better readability.";

// 换行后的代码
String veryLongString = "This is a very long string that exceeds the recommended line length "
                        + "and needs to be broken down for better readability.";

someObject.longMethodName(parameter1, parameter2,
                         parameter3, parameter4);

注释

好的注释是代码的无声文档，能够帮助自己和他人理解代码的意图和实现方式。

Java 中的注释分为如下几类：

单行注释 //：用于解释单行代码或简单的说明。
多行注释 /* … */：用于解释一段代码或提供更详细的说明。
文档注释 /** … */：用于为类、接口、方法、字段等生成 API 文档（Javadoc）。

写的注释要遵循如下的原则：

准确性：注释的内容要与代码实际的功能和逻辑保持一致。
简洁性：注释应该简洁明了，避免冗余和废话。
必要性：注释应该解释代码的意图、实现思路、特殊情况或不容易理解的部分。对于显而易见的代码，可以省略注释。
及时性：当代码被修改时，相应的注释也应该及时更新。

如下这些情况请添加注释：

类和接口的声明：使用文档注释说明类或接口的作用、设计思路、作者、版本等信息。
重要的方法：使用文档注释说明方法的功能、参数、返回值、异常情况、使用示例等。
复杂的逻辑：对于实现复杂业务逻辑的代码块，添加注释解释其实现思路和关键步骤。
重要的变量：对于重要的成员变量或局部变量，添加注释说明其含义和用途。
特殊情况或技巧：对于一些特殊的处理逻辑、边界条件或使用的技巧，添加注释进行说明。
TODO、FIXME 等标记：使用 // TODO: 标记待完成的任务，// FIXME: 标记需要修复的 Bug，// NOTE: 添加一些需要注意的事项。

/**
 * 表示一个简单的用户类。
 * 包含用户的姓名和年龄信息。
 *
 * @author Your Name
 * @version 1.0
 */
public class User {
    private String name; // 用户的姓名
    private int age;     // 用户的年龄

    /**
     * 构造一个新的 User 对象。
     *
     * @param name 用户的姓名，不能为空。
     * @param age  用户的年龄，必须为正数。
     * @throws IllegalArgumentException 如果姓名为空或年龄为负数。
     */
    public User(String name, int age) {
        if (name == null || name.isEmpty()) {
            throw new IllegalArgumentException("姓名不能为空");
        }
        if (age <= 0) {
            throw new IllegalArgumentException("年龄必须为正数");
        }
        this.name = name;
        this.age = age;
    }

    /**
     * 获取用户的姓名。
     *
     * @return 用户的姓名。
     */
    public String getName() {
        return name;
    }

    /**
     * 设置用户的姓名。
     *
     * @param name 要设置的姓名，不能为空。
     */
    public void setName(String name) {
        if (name == null || name.isEmpty()) {
            throw new IllegalArgumentException("姓名不能为空");
        }
        this.name = name;
    }

    // TODO: 添加获取年龄的方法
    public int getAge() {
        return age;
    }

    public void setAge(int age) {
        this.age = age;
    }
}