五大基本原则命名法

## 五大基本规则

#### 1. "Don't abbreviate names" (不要缩写名称)

```cpp
// 好的命名
void initializeSystem();    // 完整的单词
class TemperatureSensor;   // 完整的单词

// 不好的命名
void initSys();            // 使用了缩写
class TempSens;           // 使用了缩写
```

这条规则要求我们使用完整的单词而不是缩写，因为缩写可能会导致歧义和理解困难。

#### 2. "Don't put types in variable names" (不要在变量名中包含类型)
```cpp
// 好的命名
int counter;              // 不包含类型信息
float temperature;        // 不包含类型信息

// 不好的命名
int iCounter;            // 包含了类型信息(i)
float fTemperature;      // 包含了类型信息(f)
```
这条规则告诉我们不要在变量名中包含类型信息，因为：

- 类型信息已经在声明中明确了
- 如果类型改变，变量名也需要改变，增加了维护成本

#### 3. "Add units to variables unless the type tells you" (除非类型已经告诉你单位，否则要在变量中添加单位)
```cpp
// 好的命名
int delayMilliseconds;    // 明确标示单位是毫秒
float speedMetersPerSec;  // 明确标示单位是米/秒

// 不好的命名
int delay;               // 不清楚单位是什么
float speed;            // 不清楚速度单位
```
这条规则要求我们在变量名中明确标示单位，除非类型本身已经表明了单位。这样可以避免单位混淆导致的错误。

#### 4. "Don't put types in your types" (不要在类型名中包含类型)
```cpp
// 好的命名
class Motor;             // 简洁清晰
class Sensor;           // 直接表达意图

// 不好的命名
class AbstractMotor;     // 包含了抽象这样的类型信息
class BaseController;    // 包含了基类这样的类型信息
```
这条规则告诉我们不要在类型名称中包含像"Abstract"、"Base"这样的类型信息，因为：

- 这些词通常是多余的
- 它们使得代码更难理解和维护

#### 5. "Refactor if you find yourself naming code 'Utils'" (如果发现自己在命名代码时使用"Utils"，就需要重构)
```cpp
// 不好的命名
class StringUtils;       // 太过笼统
class Helper;           // 不清楚具体用途

// 好的命名
class StringFormatter;   // 明确表达功能
class ConfigParser;     // 清晰的职责
```
这条规则提醒我们避免使用过于笼统的名称如"Utils"或"Helper"，而是应该：

- 使用能够准确描述类职责的名称
- 如果发现需要使用"Utils"这样的名称，可能意味着这个类的职责不够清晰，需要重构

### 变量命名规则 ：
```cpp
// 局部变量使用驼峰命名法
int motorSpeed;       // 而不是 motor_speed 或 intMotorSpeed
float sensorValue;    // 而不是 sensor_val 或 fSensorValue

// 全局变量添加g_前缀
g_systemState;       // 全局系统状态变量
g_errorCount;        // 全局错误计数器

// 常量使用全大写字母加下划线
const uint32_t MAX_BUFFER_SIZE = 1024;
const float VOLTAGE_THRESHOLD = 3.3f;
```

### 添加单位说明（除非类型已经表明）
```cpp
uint32_t timeoutMillis;     // 超时时间，单位毫秒
float temperatureCelsius;   // 温度，单位摄氏度
uint16_t distanceMm;       // 距离，单位毫米
```

### 类命名规则
```cpp
// 使用清晰的名称，不要使用抽象或基类这样的词
class MotorController {    // 而不是 AbstractMotor 或 BaseMotor
    // ...
};

class TemperatureSensor {  // 而不是 TempSensor 或 TSensor
    // ...
};
```

### 函数命名规则
```cpp
// 使用动词开头，清晰表达功能
void initializeSystem();           // 而不是 sysInit
bool readSensorData();            // 而不是 getSensor
void updateMotorSpeed();          // 而不是 motorSpeedUpdate
```

### 避免使用缩写和模糊的工具类名称
```cpp
// 好的命名
class ProtocolParser {    // 而不是 ProtParser
    // ...
};

class MessageHandler {    // 而不是 MsgUtils
    // ...
};
```

### 一些特殊情况的命名规则
```cpp
// 简单循环变量可以使用简单名称
for (int i = 0; i < count; i++) { }

// 指针变量可以添加描述性前缀
uint8_t* pBuffer;        // 指向缓冲区的指针
Node* pCurrentNode;      // 指向当前节点的指针

// 中断相关函数使用特定前缀
void ISR_Timer0();       // 定时器0中断服务程序
void IRQ_UART();         // UART中断处理程序
```

```ad-note
title:需要避免的做法
1. 不要在变量名中包含类型信息（如iCount, strName）
2. 不要使用过于简单或模糊的名称（如temp, data）
3. 不要使用缩写，除非是广泛接受的缩写（如max, min）
4. 不要使用"Utils"、"Helper"这样笼统的名称
```