当前位置：首页 > news >正文

[Java 基础]Java 语言的规范

news 2025/8/13 14:09:49

代码格式

缩进：代码的层次感

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