Django实战：Python代码规范指南
文章目录
- 一、PEP 8：Python 代码风格的基石
- 二、工具推荐
- 三、命名规范
- 四、注释与文档
- 块注释
- 行内注释
- 文档字符串（Docstring）
- 五、编程实践
- 避免冗余代码
- 异常处理
- 字符串处理
- 条件判断
- 导入规范
- 类型注解
- 上下文管理器
一、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 | 数据库 |
提示：缩写应遵循行业惯例，避免自造缩写导致理解困难
四、注释与文档
好的代码需要适当的注释，但注释不应重复代码本身能表达的信息，而应补充代码背后的逻辑和思考。
块注释
用于解释一段代码的整体逻辑
"""
计算用户平均消费
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
行内注释
用于补充单行代码的关键信息，应简洁明了
x = x + 1 # 补偿浮点数计算误差（推荐：解释原因）
不推荐：对显而易见的代码添加行内注释（如x = x + 1 # x加1）
文档字符串（Docstring）
用于函数、类、模块的详细说明，使用三引号包裹
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
五、编程实践
避免冗余代码
通过函数、类或模块复用逻辑，减少复制粘贴
# 不推荐：重复代码
user1_age = 25
user1_is_adult = user1_age >= 18user2_age = 17
user2_is_adult = user2_age >= 18# 推荐：使用函数复用
def is_adult(age: int) -> bool:return age >= 18user1_is_adult = is_adult(25)
user2_is_adult = is_adult(17)
异常处理
显式捕获特定异常，避免使用裸 except。
# 不推荐：无法确定捕获哪种异常
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()。
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 显式比较。
# 不推荐
if len(items) > 0:print("有元素")# 推荐
if items:print("有元素")
导入规范
按以下顺序分组导入，每组间用空行分隔：
- 标准库
- 第三方库
- 本地模块
# 标准库
import os
import sys# 第三方库
import requests
import pandas as pd# 本地模块
from .utils import data_processor
from .config import settings
注意：避免使用from module import *，这会污染命名空间
类型注解
为函数参数和返回值添加类型注解，提高代码可读性和可维护性
def get_full_name(first: str, last: str) -> str:return f"{first} {last}"
上下文管理器
操作资源（文件、网络连接等）时，使用with语句确保资源正确释放
# 推荐
with open("data.txt", "r") as f:content = f.read()
# 文件自动关闭# 不推荐：需手动管理关闭
f = open("data.txt", "r")
content = f.read()
f.close() # 容易忘记导致资源泄漏
您正在阅读的是《Django从入门到实战》专栏！关注不迷路~