# 注释与编码规范

URL: https://caijiao.org/cpp/intro/comment-style
Source: docs/cpp/intro/comment-style.md
Description: 本节将介绍 C++ 中的注释方法和编码规范，帮助你编写可维护、易读的代码。

在 C++ 编程中，注释和编码规范不仅能提升代码的可读性，也有助于团队协作与后期维护。

## 注释

C++ 支持三种注释方式：

### 单行注释

使用 `//` 开始的注释，直到行末：

```cpp
// 这是一个单行注释
int a = 10;  // 这是行尾注释
````

### 多行注释

多行注释以 `/*` 开始，以 `*/` 结束：

```cpp
/* 这是一个多行注释
   它可以跨越多行 */
int b = 20;
```

### 文档注释

为方便生成文档，可使用 `/** */` 进行文档注释。这种方式通常与自动化工具配合使用（如 Doxygen）：

```cpp
/**
 * 这是一个文档注释
 * 用于生成 API 文档
 */
int c = 30;
```

## 编码规范

遵循统一的编码规范是编写高质量代码的关键。以下是一些常见的 C++ 编码规范：

### 1. 变量和函数命名

* **变量名**：使用小写字母和下划线（snake\_case）进行命名。例如：`int user_age;`
* **函数名**：使用小写字母和下划线，或者使用驼峰命名法（camelCase），例如：`calculate_sum()` 或 `calculateSum()`。
* **类名**：使用大写字母开头的驼峰命名法（PascalCase）。例如：`class UserProfile {}`

### 2. 缩进

* 使用 4 个空格进行缩进，不使用制表符（tab）。

### 3. 大括号

* **大括号**的位置应该紧接在控制结构后面，不应另起一行：

```cpp
if (x > 10) {
    std::cout << "x is greater than 10" << std::endl;
}
```

* **单行控制语句**（如 `if`、`for`、`while`）如果只有一个语句，括号可以省略，但建议始终使用大括号：

```cpp
if (x > 10) std::cout << "x is greater than 10" << std::endl;
```

### 4. 每行代码长度

每行代码的长度应控制在 80-100 个字符以内，避免过长的行导致代码难以阅读。

### 5. 注释规范

* 注释应简明扼要，清晰解释代码的功能。
* 不要注释显而易见的代码。例如，不需要注释 `int a = 10;`。
* 对于复杂的算法或业务逻辑，应该用注释解释为什么这么做，而不是仅仅描述代码在做什么。

### 6. 空格的使用

* 在操作符两侧应添加空格，增强可读性：

```cpp
int sum = a + b;
```

* 在函数参数和函数名之间不应有空格：

```cpp
void calculateSum(int a, int b);
```

* 在逗号、分号、运算符后面使用空格：

```cpp
for (int i = 0; i < 10; i++) {
    std::cout << i << std::endl;
}
```

### 7. 文件命名

* **源文件**：使用小写字母和下划线（snake\_case），如 `main.cpp`、`user_profile.cpp`。
* **头文件**：使用大写字母和下划线（UPPER\_SNAKE\_CASE），如 `USER_PROFILE_H`。

### 8. 类成员命名

* **私有成员变量**：以 `_` 结尾，表示私有变量。例如：`int _age;`
* **公有成员函数**：使用驼峰命名法，并以动词开头。例如：`getAge()`、`setAge()`。

## 小结

良好的注释与编码规范是高效编程的基础，能够帮助开发者更好地理解代码，提高代码质量和维护性。

* 使用适当的注释来解释代码逻辑。
* 遵循一致的命名和格式化规则。
* 保持代码的简洁和易读。