根据提供的参考资料，Python代码的编写规范旨在提高代码的可读性、一致性和可维护性，主要体现在命名规范、代码布局、注释和编程习惯等方面 [ref_2][ref_5]。以下是针对函数和变量命名的核心规范、最佳实践以及具体代码示例。 #### **1. 命名规范总则** Python的命名规范主要遵循**PEP 8**（Python Enhancement Proposal 8），其核心思想是通过命名风格来清晰表达标识符的作用域、角色和含义。主要风格如下表所示 [ref_1][ref_3]： | 命名风格 | 命名规则 | 适用场景 | 示例 | | :--- | :--- | :--- | :--- | | **蛇形命名法** | 所有字母小写，单词之间用下划线 `_` 连接 | 变量、函数、模块、包、方法 | `user_name`, `calculate_average()` | | **大驼峰命名法** | 每个单词的首字母大写，不使用下划线 | 类名、异常名、自定义类型名 | `UserAccount`, `HttpRequestError` | | **常量命名法** | 所有字母大写，单词之间用下划线 `_` 连接 | 用于定义常量（通常指值固定不变的变量） | `MAX_CONNECTIONS`, `DEFAULT_TIMEOUT` | | **单前导下划线** | 以一个下划线开头，采用蛇形命名法 | 模块/类内部使用的“私有”变量或函数 | `_internal_cache`, `_helper_method()` | | **双前导下划线** | 以两个下划线开头，采用蛇形命名法 | 用于触发Python名称改写机制的类属性 | `__private_field` | | **单/双后置下划线** | 以一个或两个下划线结尾 | 避免与Python关键字冲突 | `class_`, `object_` | #### **2. 变量命名规范** 变量命名是提高代码可读性的基础，应做到“见名知义” [ref_6]。具体规则如下： * **格式**：**蛇形命名法**，全部小写，单词间用下划线分隔 [ref_1][ref_4]。 * **命名要求**：名称应清晰、完整地描述其存储的数据或用途。避免使用单个字母（除简单的循环变量 `i`, `j`, `k` 外）、含义模糊的缩写或数字后缀 [ref_2][ref_6]。 * **避免使用**：Python的保留关键字（如 `class`, `def`, `list`）和内置函数名（如 `str`, `sum`）作为变量名。如需使用，可在末尾添加下划线，如 `class_` [ref_1]。 **代码示例（变量命名）：** ```python # 良好的变量命名 user_age = 25 customer_list = [] total_score_sum = 0.0 is_valid_input = True max_retry_count = 3 # 不佳的变量命名（不推荐） a = 25 # 含义模糊 custLst = [] # 大小写混合，缩写不清晰 sum = 0.0 # 覆盖了内置函数sum() valid = True # 可以接受，但不如is_valid_input清晰 ``` #### **3. 函数命名规范** 函数命名应清晰地反映其操作或意图，便于调用者理解其功能 [ref_5]。 * **格式**：**蛇形命名法**，全部小写，单词间用下划线分隔 [ref_1][ref_4]。函数名通常是动词或动词短语。 * **命名要求**： * 函数名应能概括其功能。对于执行某个动作的函数，通常以动词开头 [ref_2]。 * 对于返回布尔值的函数（谓词），通常以 `is_`, `has_`, `can_` 等开头 [ref_1]。 * **参数命名**：与变量命名规则一致，采用蛇形命名法。 **代码示例（函数命名）：** ```python # 良好的函数命名 def calculate_monthly_payment(principal, annual_rate, years): """计算等额本息下的月供""" monthly_rate = annual_rate / 12 / 100 months = years * 12 # ... 计算逻辑 ... return payment def is_user_active(user_id): """检查用户是否处于活跃状态""" # ... 数据库或缓存查询逻辑 ... return True def get_customer_by_id(customer_id): """根据ID获取客户信息""" # ... 查询逻辑 ... return customer_info # 不佳的函数命名（不推荐） def calc(p, r, y): # 参数缩写难以理解，函数名过于简短 pass def check(x): # 函数名和参数名都过于模糊 pass ``` #### **4. 类与模块的命名规范** 为了保持代码结构的清晰，类和模块的命名也有相应约定。 * **类名**：采用**大驼峰命名法**。类名通常是一个名词，描述该类所代表的对象 [ref_1][ref_4]。异常类名也应遵循此规则，并通常以 “Error” 或 “Exception” 结尾 [ref_1]。 ```python class UserProfile: # 良好 pass class DataParsingError(Exception): # 良好 pass class myClass: # 不佳，应使用大驼峰 pass ``` * **模块与包名**：模块文件名和包目录名应简短，全部小写，可使用下划线以提高可读性 [ref_1][ref_4]。避免与标准库模块名冲突。 ``` # 良好的模块和包命名 utils/ data_processor.py # 模块文件 config/ settings.py ``` #### **5. 常量命名规范** 常量指的是在程序运行周期内值不发生变化的变量，通常定义在模块的顶部。 * **格式**：**常量命名法**，所有字母大写，单词间用下划线分隔 [ref_1][ref_6]。 ```python # 在config.py模块顶部定义 DEFAULT_PAGE_SIZE = 20 DATABASE_CONNECTION_STRING = "postgresql://localhost/mydb" SUPPORTED_FILE_FORMATS = ('.csv', '.json', '.xlsx') ``` #### **6. 提升代码可读性的其他关键实践** 除了命名，以下实践对于编写高质量Python代码至关重要 [ref_2][ref_5][ref_6]。 * **代码布局**： * **缩进**：统一使用**4个空格**进行缩进，**绝对不要使用制表符** [ref_2][ref_5]。 * **行长度**：每行代码建议不超过79个字符，注释不超过72个字符。超长时，可利用括号、中括号或大括号在合适位置进行隐式行连接 [ref_5]。 * **空行**：使用空行分隔逻辑相关的代码块。例如，函数定义之间用两个空行，类方法定义之间用一个空行 [ref_2][ref_4]。 * **注释**： * **文档字符串**：为所有模块、类、公共函数和方法编写文档字符串，说明其用途、参数和返回值 [ref_2][ref_5]。这是最重要的注释形式。 ```python def fetch_data(url, timeout=30): """ 从指定的URL获取数据。 Args: url (str): 目标资源的URL。 timeout (int, optional): 请求超时时间（秒）。默认为30。 Returns: bytes: 获取到的原始数据。 Raises: requests.exceptions.RequestException: 当网络请求失败时抛出。 """ import requests response = requests.get(url, timeout=timeout) response.raise_for_status() return response.content ``` * **行内注释**：对复杂逻辑进行解释，放在代码行末尾，与代码至少间隔两个空格。应说明 **“为什么”** 而不是 **“是什么”** [ref_4]。 * **Pythonic编程习惯**： * **使用 `with` 语句管理资源**：如文件操作、数据库连接，确保资源被正确释放 [ref_5]。 ```python # 推荐 with open('data.txt', 'r') as file: content = file.read() # 文件已自动关闭 # 不推荐 file = open('data.txt', 'r') content = file.read() file.close() # 可能忘记调用，或在异常发生时无法调用 ``` * **利用交换赋值**：一行代码交换两个变量的值 [ref_1][ref_6]。 ```python a, b = b, a # Pythonic的交换方式 ``` * **使用列表推导式**：让创建列表的代码更简洁、更易读（在逻辑不复杂时） [ref_1]。 ```python # 将列表中的数字平方 squares = [x**2 for x in range(10)] # 简洁明了 ``` 遵循上述规范和实践，能显著提升Python代码的专业性、可读性和团队协作效率。核心是始终以“代码是给人读的”为出发点进行编写 [ref_1][ref_6]。