[Java 基础]Java 语言的规范

代码格式

缩进：代码的层次感

怎么做： 统一使用 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;}
}

代码美观

美观的代码不仅让人看着舒服，也能提高代码的可读性和维护性，从而提升开发效率。

1. 命名规范：见名知意

类名和接口名： 使用名词或名词短语，采用 PascalCase 命名法（每个单词的首字母大写，其余字母小写）。例如：UserService、ProductRepository。

方法名： 使用动词或动词短语，采用 camelCase 命名法（第一个单词的首字母小写，后续单词的首字母大写）。例如：getUserById()、calculateTotalPrice()。

变量名： 使用名词或名词短语，采用 camelCase 命名法。尽量使用具有描述性的名称。例如：userName、orderCount。

常量名： 使用大写字母，单词之间用下划线分隔。例如：MAX_VALUE、DEFAULT_TIMEOUT。

包名： 使用小写字母，单词之间用点号分隔。通常采用公司或组织的域名倒置作为前缀。例如：com.example.myapp。

2. 文件组织：清晰的目录结构

按照功能或模块将相关的类组织在不同的包中。

保持项目结构的清晰和一致性。

3. 减少魔法数字和字符串

尽量使用常量来代替代码中直接出现的数字或字符串，提高代码的可读性和可维护性。