Oracle Java编程语言代码规范 | AI生成和翻译
1. 文件组织
1.1 文件命名
- 源文件必须使用
.java扩展名 - 源文件名必须与文件中公共类的名称完全一致
- 示例：
MyClass.java包含名为MyClass的公共类CircleShape.java包含名为CircleShape的公共类
1.2 文件结构
- 开头注释
- 包声明语句
- 导入语句
- 类和接口声明
2. 格式与缩进
2.1 缩进
- 使用 4 个空格进行缩进（不要使用制表符）
- 续行缩进 8 个空格
- 大括号应垂直对齐
2.2 行长度
- 推荐最大行长度为 80 个字符
- 对于长语句，应在更高逻辑层级处换行
2.3 换行规则
- 在运算符前换行
- 新行与同级表达式的起始位置对齐
3. 注释
3.1 文件注释
- 每个源文件应以注释块开头：
```java
/*
- 类名
- 版本信息
- 日期
- 版权声明 */ ```
3.2 实现注释
- 多行注释使用
/* */ - 单行注释使用
// - 注释应解释”为什么”，而非”是什么”
3.3 文档注释
- 对类、接口、方法使用 Javadoc 风格的注释
- 包含：
- 简要描述
- 方法参数的
@param - 返回值的
@return - 异常的
@throws
4. 声明
4.1 每行声明数量
- 每行一个声明
- 推荐写法：
int level; // 正确 int size; // 正确 // 避免： int level, size; // 不推荐
4.2 初始化
- 尽可能在声明时初始化变量
- 将相关声明分组在一起
5. 语句
5.1 简单语句
- 每行一条语句
- 逗号后使用空格
- 运算符周围使用空格
5.2 复合语句
- 即使单行代码块，
if、else、for、while、do语句也要使用大括号
5.3 返回语句
- 推荐显式返回
- 在
return后避免不必要的else
6. 命名规范
6.1 包名
- 全部小写
- 唯一前缀，通常是反转的公司域名
- 示例：
com.company.project
6.2 类名
- 大驼峰命名法
- 名词或名词短语
- 示例：
DataProcessor、HttpClient
6.3 接口名
- 类似类名规则
- 考虑描述行为特征
- 示例：
Runnable、Serializable
6.4 方法名
- 小驼峰命名法
- 动词或动词短语
- 示例：
calculateTotal()、sendMessage()
6.5 变量名
- 小驼峰命名法
- 有意义且描述性强
- 除临时变量外避免使用单字母名称
6.6 常量名
- 全大写加下划线
- 示例：
MAX_VALUE、COLOR_RED
7. 编程实践
7.1 可见性
- 使用尽可能低的可见性
- 优先使用
private而非public - 对类字段使用访问器方法
7.2 变量作用域
- 在最小作用域内声明变量
- 在靠近首次使用处初始化变量
7.3 异常处理
- 异常中始终包含消息
- 捕获特定异常
- 适当使用 try-catch-finally
8. 最佳实践
8.1 避免魔法数字
- 使用命名常量替代字面量数字
- 提高代码可读性和可维护性
8.2 优先使用不可变性
- 对不改变的变量使用
final - 尽可能创建不可变类
结语
这些约定旨在提高 Java 项目代码的可读性、可维护性和一致性。