代码风格与可读性 —— 变量命名、注释、PEP8 最小集

本课导读

代码写出来是给两类读者看的：机器和人——机器只管能不能跑，人才是挑剔的那个，而那个人多半是三个月后的你。本课不学新语法，学"怎么把代码写得像话"：命名、注释、PEP8 格式最小集。这是下一课重构挑战的兵器库，也是你未来读懂开源代码、让 AI 更好地帮你写代码的基础。预计 50 分钟。

先看一场事故现场

下面这段代码能跑、结果全对——但请你试着 10 秒内说出它在干什么：

def f(a, b):
    c = []
    for i in a:
        if i[1] >= b:
            c.append(i[0])
    return c

x = [("小雨", 95), ("阿杰", 58), ("老王", 72)]
y = f(x, 60)

放弃了？现在看同一段逻辑的另一副面孔：

PASS_LINE = 60   # 及格线

def find_passed(students, pass_line):
    """从 (姓名, 分数) 列表中筛出及格的姓名"""
    passed = []
    for name, score in students:
        if score >= pass_line:
            passed.append(name)
    return passed

students = [("小雨", 95), ("阿杰", 58), ("老王", 72)]
passed_names = find_passed(students, PASS_LINE)

一行逻辑都没变，可读性天差地别。差别就来自今天的三件事：名字、注释、格式。

一、命名：让名字自己说话

命名是性价比最高的可读性投资。Python 社区的约定：

• 变量和函数：小写 + 下划线（snake_case，蛇形）：pass_line、find_passed——不是 passLine（那是其他语言的驼峰风格）
• 常量：全大写：PASS_LINE = 60、MAX_RETRY = 3——告诉读者"这个值别改"
• 见名知意：名字要回答"这是什么/干什么"——students 好过 x，find_passed 好过 f
• 几个具体禁区：
  • 单字母（循环里的 i、坐标 x y 除外——那是数学惯例）
  • data、temp、result2 这类"等于没说"的名字
  • 小写 l、大写 O——和数字 1、0 长得太像

函数名再加一条：用动词开头——find_passed（找）、calc_total（算）、send_report（发）。函数是动作，名字就该像动作。

二、注释：解释"为什么"，不是"是什么"

新手写注释最常见的误区——给每行代码配翻译：

count = 0
price, qty = 25, 3

count = count + 1   # count 加 1        ← 废话注释：代码自己会说
total = price * qty # 单价乘以数量      ← 还是废话

代码已经说清"是什么"的，不用注释再说一遍。注释的正确用途是说代码说不出的东西：

import time
scores = ["姓名/分数", 92, 88, 75]

rate = 0.008        # 汇率快照：2026-07 财务口径，每季度更新一次
time.sleep(1)       # 接口限流 1 次/秒，删掉会被封 —— 别删
scores = scores[1:] # 第一行是表头不是数据，跳过

这三条注释各自回答了一个代码答不了的问题：这个数哪来的？这行为什么必须存在？这个奇怪操作图什么？——全是"为什么"。

还有一层进阶心法：最好的注释是不需要注释。如果一段代码非得靠大段注释才能看懂，先试试改名字、拆函数——注释是补丁，清晰的代码才是本体。

三、PEP8 最小集：格式的行业默契

PEP8 是 Python 官方的代码风格指南，几十页。你现在只需要最小集——五条规矩管住 90% 的场面：

# 五条规矩演示（这段代码本身就是合格范例）

MAX_ITEMS = 3                       # ① 常量全大写


def top_sales(sales, limit=MAX_ITEMS):
  """取销量前 limit 名"""
  ranked = sorted(sales, reverse=True)   # ② 二元运算符两边加空格
  return ranked[:limit]                  # ③ 逗号后有空格，括号内侧不加


data = [180, 95, 260, 140, 320]     # ④ 函数定义之间空两行（上面 ↑）
print(top_sales(data, limit=2))     # ⑤ 关键字参数的 = 两边不加空格

对照清单：

四、AI 时代为什么更要讲风格

你可能想问：以后代码都让 AI 写，风格还重要吗？更重要了，两个原因：

1. AI 读你的代码：让 AI 帮你改 bug、加功能时，命名清晰的代码它理解得准得多——find_passed(students, pass_line) 一眼懂，f(a, b) 它也得猜。风格好的代码，AI 是加速器；风格差的，AI 陪你一起猜。
2. 你审 AI 的代码：AI 生成的代码你得看得懂才敢用（阶段 0 学过：AI 输出必须验证）。练出"什么是好代码"的品味，你才有能力当审稿人，而不是复制粘贴工。

一个立刻能用的招：把你的代码发给 AI，说"请按 PEP8 和可读性最佳实践点评这段代码，指出改进点"——这就是免费的代码审查（code review），高手成长最快的路径之一。

✍️ 练习

练习 1：命名急诊

下面每个名字都有毛病。按约定改好（不用运行，写出改法即可，答案里对照）。

passLine = 60          # 毛病 1
def Chuli(x):          # 毛病 2（这个函数的功能是：算列表平均值）
    return sum(x) / len(x)
l = [1, 2, 3]          # 毛病 3
maxretry = 5           # 毛病 4（这是个不该被修改的配置值）

pass_line = 60          # 驼峰 → 蛇形
def calc_average(nums): # 拼音+首字母大写+意义不明 → 动词开头的英文蛇形；x → nums
    return sum(nums) / len(nums)
scores = [1, 2, 3]      # 小写 l 和 1 太像，且不知装什么 → 按内容起名
MAX_RETRY = 5           # 配置常量 → 全大写

练习 2：注释断案

判断每条注释是"废话注释"还是"合格注释"，废话的说明为什么。

n = n + 1                  # A. n 增加 1
prices = prices[2:]        # B. 前两行是测试数据，正式统计要跳过
name = input()             # C. 获取用户输入
retry = 3                  # D. 客服系统最多重拨 3 次是运营商限制，别调大

练习 3：小重构（挑战，下一课的预演）

按今天的三件套（命名/注释/格式），把这段能跑但邋遢的代码整理成体面的样子。逻辑不许变，改完运行结果应一致：输出统计结果。

# 整理下面的代码
def f(a):
  b=[]
  for x in a:
      if x>=1000:b.append(x)
  c=len(b)
  return c,sum(b)

d=[820,1150,930,1240,1080]
e,g=f(d)
print(e,g)

HOT_LINE = 1000   # 爆款判定线：日访问量


def count_hot_days(visits, hot_line=HOT_LINE):
    """统计爆款天数和爆款日的总访问量，返回 (天数, 总量)"""
    hot_days = [v for v in visits if v >= hot_line]
    return len(hot_days), sum(hot_days)


daily_visits = [820, 1150, 930, 1240, 1080]
hot_count, hot_total = count_hot_days(daily_visits)
print(hot_count, hot_total)

📝 随堂测验

本课小结

• 命名：变量/函数用蛇形且见名知意，函数动词开头，常量全大写；起不出好名先想清职责
• 注释：解释为什么，不复读是什么；函数配 docstring；最好的注释是不需要注释
• PEP8 最小集五条：运算符空格、逗号空格、关键字参数不空格、4 空格缩进、行别太长——将来交给格式化工具
• AI 时代风格更值钱：好代码让 AI 帮得准，好品味让你审得动

下一课是本单元关卡：一份综合测验 + 一段真正的烂代码等你重构——把这六课的功夫一次亮出来。