### 函数命名规范

本规范旨在通过统一、清晰的函数命名来提高代码的可读性和可维护性。核心思想是使用**动词前缀**来明确标识函数的**意图**和**操作类型**。

#### 1. 数据操作 (Data Manipulation)

| 前缀      | 含义                         | 示例                                      | 说明                                                 |
| :-------- | :--------------------------- | :---------------------------------------- | :--------------------------------------------------- |
| `create_` | 创建一条新记录或资源         | `create_user({name: 'Alice'})`            | 通常对应 RESTful 中的 POST 操作。                    |
| `fetch_`  | **从远程源 (网络)** 获取数据 | `fetch_user_list()`                       | 明确表示有网络 I/O 操作，可能异步。                  |
| `grab_`   | **从本地源** 获取或抓取数据  | `grab_local_config()`                     | 明确表示无网络操作，如读取本地存储、缓存、状态等。   |
| `update_` | 更新已存在的记录或资源       | `update_user_email(123, 'new@email.com')` | 通常对应 RESTful 中的 PUT/PATCH 操作。               |
| `delete_` | 删除一条记录或资源           | `delete_post(456)`                        | 通常对应 RESTful 中的 DELETE 操作。                  |
| `save_`   | 保存数据 (本地或远程)        | `save_user_preferences()`                 | 通用保存，上下文需明确是本地保存还是调用 `update_`。 |

#### 2. 动作与执行 (Actions & Execution)

| 前缀           | 含义                           | 示例                           | 说明                                       |
| :------------- | :----------------------------- | :----------------------------- | :----------------------------------------- |
| `execute_`     | 执行一个复杂的行为、命令或流程 | `execute_data_export()`        | 强调操作的复杂性和执行性，而不仅仅是计算。 |
| `do_`          | 执行一个通用操作               | `do_cleanup()`                 | 一个通用的、不属于其他明确类别的前缀。     |
| `authenticate` | 执行身份验证流程               | `authenticate_with_password()` | 通常用于登录、验证令牌等。                 |
| `handle_`      | 处理一个特定的事件或输入       | `handle_button_click()`        | 常用于事件处理函数。                       |
| `submit_`      | 提交一个表单或一组数据         | `submit_order_form()`          | 强调完成的动作。                           |

#### 3. 验证与检查 (Validation & Checks)

| 前缀        | 含义                            | 示例                      | 说明                                        |
| :---------- | :------------------------------ | :------------------------ | :------------------------------------------ |
| `validate_` | 验证数据是否符合规则            | `validate_email_format()` | 通常返回错误信息或布尔值，但不改变状态。    |
| `is_`       | **返回布尔值** 的判断           | `is_user_logged_in()`     | 函数名本身就是一个问题的答案 (是 / 否)。    |
| `has_`      | **返回布尔值** 的存在性检查     | `has_permission('admin')` | 检查某物是否存在或是否拥有某种属性 / 权限。 |
| `can_`      | **返回布尔值** 的权限或能力检查 | `can_user_edit(post)`     | 检查是否被授权或有能力执行某项操作。        |

#### 4. 生成与转换 (Generation & Transformation)

| 前缀          | 含义                         | 示例                     | 说明                                 |
| :------------ | :--------------------------- | :----------------------- | :----------------------------------- |
| `_gen` (后缀) | 生成数据                     | `generate_report()`      | 创建一个新的、复杂的数据结构或输出。 |
| `convert_`    | 将数据从一种形式转换为另一种 | `convert_json_to_xml()`  | 强调格式或类型的转换。               |
| `format_`     | 格式化数据以供显示           | `format_date(timestamp)` | 为 UI 显示做准备。                   |
| `parse_`      | 解析原始数据 (如字符串)      | `parse_csv_string(data)` | 从原始输入中提取结构化信息。         |

---

### 最佳实践与建议

1. **组合使用**：前缀可以与域名组合，形成非常清晰的名称。

   - `fetch_` + `User` + `Profile` = `fetch_user_profile()`
   - `validate_` + `Product` + `Form` = `validate_product_form()`
   - `is_` + `Form` + `Valid` = `is_form_valid()`

2. **保持一致性**：在同一个项目或代码库中，对相同的操作坚持使用相同的前缀。

3. **使用动词**：函数名应该始终以动词开头，描述它**做什么**。

4. **明确来源**：区分 `fetch_` (远程) 和 `grab_` (本地) 对于理解代码的性能和副作用至关重要。

5. **布尔函数即问题**：`is_`， `has_`， `can_` 开头的函数应该总是返回一个布尔值 (`true`/`false`)，并且读起来应该像一个疑问句。

6. **避免模糊的命名**：像 `process_data()` 或 `handle_data()` 这样的名称不如 `validate_data()` 或 `transform_data()` 来得清晰。尽量使用最具体的前缀。

通过遵循这套规范，您的代码将更容易被您自己和团队其他成员阅读、理解和维护。
