JAVA基础 - 代码规范

[一. 命名规范](#一. 命名规范)

[二. 注释规范](#二. 注释规范)

[三. 地标注释](#三. 地标注释)

[四. 代码排版](#四. 代码排版)

[五. 空格规范](#五. 空格规范)

一. 命名规范

类名

使用大驼峰命名法，即每个单词的首字母大写，例如：StudentInfo、ProductManager 。
类名应该是名词，并且能够准确地反映出类的用途或功能。

方法名

使用小驼峰命名法，第一个单词小写，后续单词首字母大写，例如：getStudentName、calculateSum 。
方法名应该是动词或动词短语，清晰地表达方法的行为或操作。

变量名

遵循小驼峰命名法，例如：studentAge、totalCount 。
变量名应该具有描述性，能够准确反映变量所存储的数据的含义。

常量名

全部大写，单词之间用下划线分隔，例如：MAX_VALUE、MIN_LENGTH 。
常量名应该使用能够明确表达其常量值含义的名称。

包名

全部小写，使用点号分隔各个层次，例如：com.example.project.module 。
包名应该基于项目的组织结构和功能模块进行命名，通常反映了代码的层次结构和所属的领域。

参数名

与变量名的命名规则相同，使用小驼峰命名法，例如：inputData、resultFlag 。

接口名

与类名的命名规则相同，使用大驼峰命名法，例如：IStudentService 。

遵循这些命名规范可以使 Java 代码更具可读性、可理解性和可维护性。它有助于开发人员快速理解代码的结构和功能，减少代码中的混淆和错误。

例如，在一个学生管理系统中，可能有以下的命名：

java 复制代码

class Student {
    private int studentId;
    private String studentName;

    public void setStudentName(String newStudentName) {
        // 方法实现
    }

    public String getStudentName() {
        // 方法实现
    }
}

这样的命名清晰地表明了每个元素的用途和性质。

二. 注释规范

1. 单行注释（//）

用于简短的说明，通常在代码行的末尾。
示例： int age = 20; // 学生的年龄

2. 多行注释（/* */）

用于较长的注释内容，可以跨越多行。
通常用于对方法、类、代码块进行说明。
示例：

/*
- 这个方法用于计算两个数的和
- 参数 num1 和 num2 是要相加的两个数
- 返回值是它们的和
  */
  public int addNumbers(int num1, int num2) {
  return num1 + num2;
  }

3. 文档注释（/ /）*

用于生成 API 文档，通常在类、方法和字段的声明之前。
包含对类、方法、参数、返回值等的详细说明。
示例：

/**
- 学生类，代表学生的基本信息
  */
  public class Student {
  private int id;
  
  /**
  - 构造函数，用于初始化学生对象
  - @param id 学生的唯一标识符
    */
    public Student(int id) {
    this.id = id;
    }
  /**
  - 获取学生的 ID
  - @return 学生的 ID
    */
    public int getId() {
    return id;
    }
    }

注释的原则

注释应该清晰、准确、简洁，避免冗长和模糊的描述。
注释应该与代码保持同步更新，确保注释的内容与实际代码的功能一致。
对于复杂的算法或逻辑，注释应该解释其工作原理和思路。
避免注释掉大量的代码，如果代码不再使用，应该删除而不是注释。

遵循良好的注释规范可以提高代码的可读性和可维护性，帮助其他开发人员更好地理解您的代码。

三. 地标注释

常见的约定包括：

//todo：表示此处有待处理的任务，或代码没有编写完成。
//fixme：说明此处代码是错误的，需要修正。
//xxx: 说明此处代码实现功能,待优化

例如：

public class SomeClass {
    public void someMethod() {
        //todo: 需要实现这个方法的具体功能
        //fixme: 这里有个潜在的问题，需要进一步检查和修正
    }
}

这样其他开发者在阅读代码时，可以快速了解到哪些地方需要进一步处理或存在问题。

四. 代码排版

缩进

通常使用 4 个空格作为缩进单位，而不是制表符（Tab）。这有助于在不同的编辑器和环境中保持一致的缩进显示。

换行

每行代码的长度不宜过长，一般建议不超过 80 到 120 个字符。如果一行代码过长，可以根据逻辑在适当的位置换行，例如在运算符后。

对于方法调用，如果参数较多，每个参数应该单独占据一行，并适当缩进。

空行

在不同的方法之间、类的成员变量和方法之间、逻辑块之间使用空行来增强代码的可读性和区分度。

括号

左括号 ( 与方法名或控制语句在同一行，右括号 ) 单独占据一行，并且与左括号对齐。

代码块

对于 if 、 for 、 while 等控制结构的代码块，如果代码块中只有一行语句，可以不使用大括号 {} ；但如果有多行语句，必须使用大括号来明确代码块的范围。

声明和初始化

一个声明语句只声明一个变量，并且尽量在靠近首次使用的位置进行声明和初始化。

以下是一个示例，展示了良好的 Java 代码排版：

java 复制代码

public class CodeFormatExample {

    private int num1;
    private int num2;

    public void calculateSum() {
        int sum = 0;

        // 计算两个数的和
        if (num1 > 0 && num2 > 0) {
            sum = num1 + num2;
            System.out.println("两数之和: " + sum);
        } else {
            System.out.println("输入的数不合法");
        }
    }

    public static void main(String[] args) {
        CodeFormatExample example = new CodeFormatExample();
        example.num1 = 5;
        example.num2 = 10;
        example.calculateSum();
    }
}

良好的代码排版可以使代码更易于阅读、理解和维护，提高代码的质量和开发效率。

五. 空格规范

1. 运算符两侧

在大多数运算符（如 + 、 - 、 * 、 / 、 = 等）的两侧应该添加一个空格，以增强代码的可读性。

例如：

java 复制代码

int a = 10 + 20;
double b = 5.0 * 3.0;

2. 逗号后

在逗号 , 后面应该添加一个空格。

例如：

int[] numbers = {1, 2, 3, 4, 5};

3. 方法调用的参数之间

在方法调用时，每个参数之间应该用一个空格分隔。

例如：

printMessage("Hello", "World");

4. 控制语句

在控制语句（如 if 、 for 、 while 等）的括号内，表达式与括号之间不应该添加空格，但在关键字和括号之间应该添加一个空格。

例如：

if (condition) {
    // 代码块
}

for (int i = 0; i < 10; i++) {
    // 代码块
}

5. 数组初始化

在数组初始化时，每个元素之间应该用一个空格分隔。

例如：

int[] arr = {10, 20, 30, 40, 50};

6. 类型转换

在进行类型转换时，括号与表达式之间不应该添加空格。

例如：

double result = (double) num;

遵循这些空格规范可以使 Java 代码更加清晰、易读和易于维护。