# Python 包、模块、类、函数、变量命名规范

本文档总结 Python 中常见命名规则，便于编写清晰、可维护、符合 PEP 8 的代码。

## 1. 总体原则

- 命名要清晰、准确、可读
- 优先使用英文单词或英文短语
- 避免使用模糊、不规范的名称
- 保持命名风格统一
- 不要与 Python 内置名称冲突

## 2. 包（Package）命名规范

### 规则

- 全部使用小写字母
- 尽量使用简短、表达清晰的词
- 多个单词建议使用下划线连接
- 避免使用大写字母或中文

### 推荐示例

```python
package_name
user_service
data_utils
```

### 不推荐示例

```python
UserService
userService
DATA_UTILS
```

### 适用场景

- 目录名
- 项目中逻辑模块的分组名

## 3. 模块（Module）命名规范

### 规则

- 全部使用小写字母
- 多个单词用下划线分隔
- 文件名应体现功能或职责
- 以 `.py` 结尾

### 推荐示例

```python
user_service.py
math_utils.py
config_loader.py
```

### 不推荐示例

```python
UserService.py
userservice.py
mathutils.py
```

### 说明

模块名应尽量体现内容，例如：
- `user_service.py`：用户相关服务
- `file_utils.py`：文件处理工具
- `config_loader.py`：配置加载器

## 4. 类（Class）命名规范

### 规则

- 使用 PascalCase（大驼峰命名法）
- 每个单词首字母大写
- 类名通常是名词或名词短语

### 推荐示例

```python
class UserProfile:
    pass

class HttpClient:
    pass

class DataProcessor:
    pass
```

### 不推荐示例

```python
class userProfile:
    pass

class http_client:
    pass
```

### 说明

类一般用于表示实体、对象或能力集合，例如：
- `UserProfile`
- `OrderService`
- `FileManager`

## 5. 函数（Function）命名规范

### 规则

- 使用 snake_case（蛇形命名法）
- 通常是动词或动词短语
- 函数名应该清楚说明作用

### 推荐示例

```python
def get_user_name():
    pass

def calculate_total():
    pass

def save_to_file():
    pass
```

### 不推荐示例

```python
def GetUserName():
    pass

def total():
    pass
```

### 说明

函数名通常以“动作”开头，例如：
- `read_file()`
- `send_email()`
- `validate_password()`

## 6. 变量 / 标量（Variable / Scalar）命名规范

### 规则

- 使用 snake_case
- 变量名要表达含义，尽量避免单字母（除循环变量外）
- 常量使用大写字母 + 下划线
- 布尔变量前缀常用 `is_`、`has_`、`can_`

### 推荐示例

```python
user_name = "Tom"
age = 18
total_price = 99.9
is_active = True
has_permission = False
```

### 不推荐示例

```python
x = "Tom"
n = 18
a = True
```

### 说明

变量名应该尽量说明数据是什么，例如：
- `user_name`
- `max_score`
- `retry_count`
- `is_valid`

## 7. 常量（Constant）命名规范

### 规则

- 全部大写
- 单词之间用下划线连接
- 常量通常在模块级别声明

### 推荐示例

```python
MAX_RETRY = 5
DEFAULT_TIMEOUT = 30
PI = 3.1415926
```

### 不推荐示例

```python
MaxRetry = 5
defaultTimeout = 30
```

## 8. 私有命名规范

### 规则

- 私有变量或函数前加单下划线：`_name`
- 更强私有时使用双下划线：`__secret`
- 但不要过度使用双下划线，除非确实需要名称改写

### 示例

```python
_secret_key = "abc"

class Demo:
    def __private_method(self):
        pass

    def public_method(self):
        self.__private_method()
```

## 9. 避免命名冲突

不要使用 Python 内置名称，例如：

```python
list
str
sum
dict
set
int
```

如果必须使用，建议加上更明确的前后缀，比如：

```python
list_data
user_dict
```

## 10. 命名风格一览

| 类型 | 命名方式 | 示例 |
| --- | --- | --- |
| 包 | lower_case | `data_utils` |
| 模块 | snake_case | `file_handler.py` |
| 类 | PascalCase | `UserManager` |
| 函数 | snake_case | `calculate_total()` |
| 变量 | snake_case | `student_name` |
| 常量 | UPPER_SNAKE_CASE | `MAX_RETRY` |

## 11. 推荐命名模板

```python
# 包
package_name

# 模块
module_name.py

# 类
class UserAccount:
    pass

# 函数
def create_user_account():
    pass

# 变量
user_name = "Alice"
account_balance = 1000

# 常量
MAX_LOGIN_ATTEMPTS = 5
```

## 12. 最佳实践

- 名称要表意，不要使用无意义缩写
- 优先使用准确、清晰、标准的英文单词
- 统一命名风格，避免混用 camelCase、PascalCase 和 snake_case
- 变量名尽量描述“是什么”，函数名尽量描述“做什么”
- 常量统一使用大写字母加下划线

## 13. 一句话总结

Python 命名规范的核心是：

- 包：小写，简洁清晰
- 模块：小写下划线，功能导向
- 类：PascalCase，名词化
- 函数：snake_case，动词化
- 变量/标量：snake_case，表达含义
- 常量：UPPER_SNAKE_CASE

遵循这些规则后，代码会更容易阅读、维护和协作。