# 整洁代码规则

## 你必须遵守的核心原则

### 1. 可读性优先原则（最高优先级）

**执行要求：**

- **必须**：代码是写给人看的，机器只是顺便执行
- **必须**：使用有意义的变量名和函数名
- **必须**：代码应该自解释，减少不必要的注释
- **禁止**：使用无意义的变量名（如 `a`, `b`, `x`, `temp`）

**命名要求：**

- 变量名必须清楚表达其用途
- 函数名必须清楚表达其功能
- 类名必须清楚表达其职责

### 2. 单一职责原则（必须遵守）

**函数要求：**

- **必须**：每个函数只做一件事
- **必须**：函数名必须准确描述函数的功能
- **禁止**：一个函数做多件不相关的事

**类要求：**

- **必须**：每个类只有一个改变的理由
- **必须**：类的职责必须清晰明确
- **禁止**：创建职责混乱的"上帝类"

**代码要求：**

- **必须**：保持函数和类的简洁
- **必须**：如果函数或类变得复杂，必须拆分

### 3. DRY 原则（禁止重复）

**执行要求：**

- **禁止**：编写重复代码
- **必须**：提取公共逻辑到函数或类中
- **必须**：使用配置而非硬编码
- **必须**：识别并消除重复模式

## 命名规范（必须遵守）

### 变量和函数命名

- **必须**：使用描述性的名称，避免缩写
- **必须**：函数名应该是动词或动词短语（如 `calculateTotal`, `getUserById`）
- **必须**：类名应该是名词或名词短语（如 `UserService`, `OrderProcessor`）
- **必须**：布尔变量应该使用 is/has/can 等前缀（如 `isValid`, `hasPermission`, `canEdit`）
- **禁止**：使用单字母变量名（除非是循环计数器）
- **禁止**：使用误导性的名称

### 常量命名

- **必须**：常量应该使用全大写，单词间用下划线分隔（如 `MAX_RETRY_COUNT`, `DEFAULT_TIMEOUT`）
- **必须**：魔法数字和字符串必须定义为常量

## 函数设计规范（必须遵守）

### 函数长度

- **必须**：函数应该短小，最好不超过 20 行
- **必须**：如果函数超过 20 行，考虑拆分
- **必须**：函数应该只做一件事，做好一件事

### 函数参数

- **必须**：函数参数应该尽可能少，最好不超过 3 个
- **必须**：如果参数超过 3 个，考虑使用对象或配置类
- **禁止**：使用布尔参数控制函数行为（使用策略模式或函数重载）

### 函数行为

- **必须**：避免副作用，函数应该可预测
- **必须**：函数应该返回一致的结果类型
- **禁止**：函数既修改状态又返回值（除非明确需要）

## 代码组织规范（必须遵守）

### 代码布局

- **必须**：相关代码应该放在一起
- **必须**：使用空行分隔逻辑块
- **必须**：保持一致的代码风格
- **必须**：遵循项目的代码格式化规范

### 代码清理

- **必须**：删除未使用的代码
- **必须**：删除过时的注释
- **必须**：删除调试代码（如 `console.log`, `print` 语句）
- **禁止**：提交包含调试代码的代码

## 代码示例

### ❌ 不好的实践

```python
def calc(x, y, z):
    return x * y + z * 2

def process(data):
    # 处理数据
    result = []
    for i in data:
        if i > 0:
            result.append(i * 2)
    return result
```

### ✅ 好的实践

```python
TAX_MULTIPLIER = 2.0

def calculate_total_price(quantity: int, unit_price: float, tax_rate: float) -> float:
    subtotal = quantity * unit_price
    tax = subtotal * tax_rate
    return subtotal + tax

def filter_and_double_positive_numbers(numbers: list[int]) -> list[int]:
    """过滤正数并翻倍"""
    return [number * 2 for number in numbers if number > 0]
```

## 代码质量检查清单

在提交代码前，你必须确认：

- [ ] 所有变量和函数都有有意义的名称
- [ ] 函数长度不超过 20 行（或合理长度）
- [ ] 函数参数不超过 3 个
- [ ] 没有重复代码
- [ ] 没有未使用的代码和注释
- [ ] 代码格式符合项目规范
- [ ] 代码自解释，不需要过多注释
- [ ] 每个函数只做一件事
- [ ] 每个类职责单一
