外观
Python代码规范指南
PEP 8：Python 代码风格的基石
在团队协作和项目维护中，一致的代码风格至关重要。它不仅能提高代码的可读性，还能减少沟通成本，提升开发效率。
PEP 8 是 Python 官方发布的代码风格指南，全称为《Style Guide for Python Code》。它由 Guido van Rossum（Python 创始人）等人制定，目的是统一 Python 代码的编写风格，让不同开发者编写的代码都能保持一致的 "Python 味"。可以通过官方文档 Style Guide for Python Code深入学习 PEP 8 的全部内容，但掌握核心规范足以应对大多数开发场景。
工具推荐
遵循代码规范不必全靠人工检查，现代开发工具能帮我们自动处理大部分风格问题
格式化工具
- PyCharm：内置 PEP 8 支持，通过
Ctrl+Alt+L（Windows）或Cmd+Opt+L（Mac）可一键格式化代码 - VS Code：安装
Python和Black Formatter插件后，可配置保存时自动格式化
静态检查工具
- flake8：集成立即检查代码风格问题和常见错误
- mypy：配合类型注解进行静态类型检查，提前发现潜在问题
推荐工具链：Black + flake8 的组合可以实现自动化检查和格式化，大幅减少人为处理风格问题的精力消耗。同时，合理利用 AI 辅助编程工具（如 通义灵码）也能在编写时就保持规范。
命名规范
良好的命名是代码可读性的基础，Python 对不同类型的标识符有明确的命名约定
| 类型 | 命名规则 | 示例 |
|---|---|---|
| 变量 / 函数 | 小写字母，单词间用下划线分隔（snake_case） | user_id, get_user_data |
| 类名 | 每个单词首字母大写（PascalCase，大驼峰） | UserProfile, OrderProcessor |
| 常量 | 全大写字母，单词间用下划线分隔 | MAX_RETRY_COUNT, DEBUG_MODE |
| 私有属性 / 方法 | 单下划线开头（表示弱内部使用） | _calculate_total |
| 特殊方法 | 双下划线开头和结尾（魔术方法） | __init__, __str__ |
常用缩写参考
在保证可读性的前提下，合理使用缩写可以简化命名
| 原词 | 缩写 | 说明 |
|---|---|---|
| Identifier | id | 标识符 |
| Message | msg | 消息 |
| Number | num | 数字 |
| Length | len | 长度 |
| Index | idx | 索引 |
| Value | val | 值 |
| Parameter | param | 参数 |
| Temporary | tmp | 临时 |
| Configuration | config/cfg | 配置 |
| Database | db | 数据库 |
TIP
缩写应遵循行业惯例，避免自造缩写导致理解困难
注释与文档
好的代码需要适当的注释，但注释不应重复代码本身能表达的信息，而应补充代码背后的逻辑和思考。
块注释
用于解释一段代码的整体逻辑
python
"""
计算用户平均消费
1. 过滤掉无效订单（金额<=0）
2. 计算有效订单总金额
3. 除以有效订单数量得到平均值
"""
valid_orders = [o for o in orders if o.amount > 0]
total = sum(o.amount for o in valid_orders)
avg = total / len(valid_orders) if valid_orders else 0行内注释
用于补充单行代码的关键信息，应简洁明了
python
x = x + 1 # 补偿浮点数计算误差（推荐：解释原因）不推荐：对显而易见的代码添加行内注释（如x = x + 1 # x加1）
文档字符串（Docstring）
用于函数、类、模块的详细说明，使用三引号包裹
python
def calculate_discount(price: float, rate: float) -> float:
"""
计算折扣后的价格
参数:
price (float): 原价
rate (float): 折扣率（0-1之间）
返回:
float: 折扣后价格
异常:
ValueError: 当折扣率不在0-1范围内时抛出
"""
if not 0 <= rate <= 1:
raise ValueError("折扣率必须在0到1之间")
return price * rate编程实践
避免冗余代码
通过函数、类或模块复用逻辑，减少复制粘贴
python
# 不推荐：重复代码
user1_age = 25
user1_is_adult = user1_age >= 18
user2_age = 17
user2_is_adult = user2_age >= 18
# 推荐：使用函数复用
def is_adult(age: int) -> bool:
return age >= 18
user1_is_adult = is_adult(25)
user2_is_adult = is_adult(17)异常处理
显式捕获特定异常，避免使用裸 except。
python
# 不推荐：无法确定捕获哪种异常
try:
result = divide(a, b)
except:
print("发生错误")
# 推荐：捕获特定异常
try:
result = divide(a, b)
except ZeroDivisionError:
print("除数不能为零")
except TypeError:
print("参数类型错误")字符串处理
优先使用 f-string（Python 3.6+）或 str.format()。
python
name = "Alice"
age = 30
# 推荐
greeting = f"Hello, {name}! You are {age} years old."
# 也可使用，但不如f-string直观
greeting = "Hello, {}! You are {} years old.".format(name, age)条件判断
直接判断对象真假，避免与 True/False/None 显式比较。
python
# 不推荐
if len(items) > 0:
print("有元素")
# 推荐
if items:
print("有元素")导入规范
按以下顺序分组导入，每组间用空行分隔：
- 标准库
- 第三方库
- 本地模块
python
# 标准库
import os
import sys
# 第三方库
import requests
import pandas as pd
# 本地模块
from .utils import data_processor
from .config import settingsWARNING
避免使用from module import *，这会污染命名空间
类型注解
为函数参数和返回值添加类型注解，提高代码可读性和可维护性
python
def get_full_name(first: str, last: str) -> str:
return f"{first} {last}"上下文管理器
操作资源（文件、网络连接等）时，使用with语句确保资源正确释放
python
# 推荐
with open("data.txt", "r") as f:
content = f.read()
# 文件自动关闭
# 不推荐：需手动管理关闭
f = open("data.txt", "r")
content = f.read()
f.close() # 容易忘记导致资源泄漏