◆ CODE REVIEW 101 · 新人工程师手册 封面
新入职程序员 · 入门培训 · 第 1 讲

代码规范审查与
重构建议入门

写出让人看得懂、改得动、放得心的代码 —— 从第一天开始

⏱ 约 30 分钟🎯 零基础友好🧰 附自查清单
git commit -m "feat: 规范起步"
// code review ✔ approved
团队代码审查协作插画
COURSE MAP

这节课我们将走过 5 站

每一站都为「刚入职的你」量身定制,点击卡片可直接跳转

CH.01
01

为什么要做代码规范审查

质量、协作、可维护性——审查不只是"挑毛病"

CH.02
02

常见代码坏味道

超长函数、魔法数字、重复代码……前后对比一看就懂

CH.03
03

评审沟通礼仪与流程

对事不对人,话怎么说、流程怎么走

CH.04
04

常用重构手法入门

提取函数、重命名、消除重复——三个最常用的动作

CH.05
05

新人自查清单

提交代码前,花 5 分钟过一遍这份清单

01

为什么要做
代码规范审查?

  • 审查 = 团队给代码做的「体检」
  • 问题在上线前被发现,成本最低
  • 它是新人融入团队最快的通道
盾牌守护代码质量插画
CH.01 · WHY

代码审查带来的三大价值

别把它当成「被挑刺」,它是团队互相帮忙的日常仪式

🛡️

① 质量:少出事故

再细心的开发者也有盲区。多一双眼睛,逻辑漏洞、边界错误、安全隐患往往在上线前就被拦下——修复成本几乎是最低的。

把问题拦在上线前
🤝

② 协作:知识流动

通过互相阅读代码,你能了解其他模块怎么写、团队的惯例是什么;别人也认识了你。人员休假、离职时,代码不会变成「无人区」。

代码是团队的共同语言
🧭

③ 可维护性:守住底线

统一的规范让「半年后的你自己」也能看懂今天的代码。规范的代码改起来放心、扩展起来迅速,技术债不再悄悄滚雪球。

今天多写注释,明天少掉头发
CH.01 · WHY

如果没有规范审查……技术债会滚雪球

一个坏味道不可怕,可怕的是它被不断复制、放大

❄️

一颗小雪球

某个函数图省事,
写死了几个魔法数字

➜
⛄

照猫画虎

后来的同事「参考」
同样的写法继续堆

➜
🌨️

积重难返

没人敢动的核心模块,
改一行、崩三处

➜
💥

雪崩式代价

最后只能推倒重写,
耗时数倍还耽误业务

💡 新人视角的真实场景:接手一位离职同事的项目——一个函数 800 行、满屏数字含义不明、注释停留在三年前。每一处「当时懒得改」,都在为未来的你挖坑。代码审查,就是把坑填在最早的季节。
02

常见代码坏味道

  • 「坏味道」= 代码里不健康的信号
  • 三个高频选手:超长函数、魔法数字、重复代码
  • 每组都有「修改前 → 修改后」对照
放大镜发现代码坏味道插画
CH.02 · 坏味道 ①

超长函数:一个函数干十件事

症状:一个函数几百行、缩进套缩进、注释比代码还多——没人敢改

BEFORE❌ 修改前 · 巨无霸函数
def process_order(order): # 校验、算折扣、扣库存、发短信、 # 记日志…… 全部挤在一起(60+ 行) if order.total > 100 and order.user.vip == True: price = order.total * 0.9 else: price = order.total if price > 500: stock = db.query("...") # …… 20 行扣库存逻辑 sms.send(order.phone, "已下单") log.write("order done") # …… 还有 30 行 😵
⚠️ 问题:读不懂、测不了、改一处怕崩全局——典型的「没人敢碰」代码
AFTER✅ 修改后 · 意图分层
def process_order(order): price = apply_discount(order) reserve_stock(order) notify_user(order) log_order(order) # 主流程 4 行,像目录一样清晰; # 每个子函数只做一件事, # 可以单独阅读、单独测试。
✅ 要点:函数名即目录。主流程一眼看懂,细节按需下钻,改动影响范围可控
📏经验法则:一个函数尽量不超过一屏(约 30~50 行);如果注释里出现「第一步 / 第二步 / 第三步」,就说明它该拆了。
CH.02 · 坏味道 ②

魔法数字:来历不明的神秘值

症状:代码里凭空出现 0.88、60、3……三个月后没人知道它们是什么意思

BEFORE❌ 修改前 · 满屏咒语
if score >= 60: print("及格") discount = price * 0.88 if status == 3: send_reminder() # 60 是什么?0.88 谁定的?3 代表啥? # 只能去问三个月前的自己 🫠
⚠️ 问题:含义靠猜;同一个值散落多处,改漏一处就是线上事故
AFTER✅ 修改后 · 有名有姓
PASS_SCORE = 60 # 及格线 VIP_DISCOUNT = 0.88 # VIP 统一折扣 STATUS_PENDING = 3 # 待提醒状态 if score >= PASS_SCORE: ... discount = price * VIP_DISCOUNT if status == STATUS_PENDING: ...
✅ 要点:常量「见名知义 + 集中管理」,改折扣只动一行,全局生效
✨判断口诀:代码里出现的每个裸数字/字符串,问一句「它是什么?」——答不上来,就给它一个名字。
CH.02 · 坏味道 ③

重复代码:复制粘贴的债务

症状:两段几乎一样的代码分居两处——改 bug 时永远会漏掉一处

BEFORE❌ 修改前 · 双胞胎代码
# 销售部发周报 smtp = connect("smtp.example.com") smtp.login("sales_bot", "s3cret") smtp.send("sales@ex.com", "周报", body) # 研发部发周报(几乎一模一样) smtp = connect("smtp.example.com") smtp.login("dev_bot", "s3cret") smtp.send("dev@ex.com", "周报", body)
⚠️ 问题:SMTP 密码改了要记得改两个地方;下周再加「财务部」,又要复制一遍
AFTER✅ 修改后 · 一处定义
def send_weekly_report(sender, to, body): smtp = connect(SMTP_SERVER) smtp.login(sender, get_password(sender)) smtp.send(to, "周报", body) send_weekly_report("sales_bot", "sales@ex.com", body) send_weekly_report("dev_bot", "dev@ex.com", body)
✅ 要点:变化的部分做成参数,公共逻辑只写一份——一处修改,处处生效
🧹三招识别:搜同名的变量名、Ctrl+C/V 记录、Code Review 里的「似曾相识」感——发现重复,立刻抽成函数。
CH.02 · 坏味道 速查表

其他高频坏味道,一眼识别

评审时看到这些信号,就可以礼貌地提出来了

🌀

深层嵌套

if 套 if 套 for 套 if,读到第五层已忘记开头

↳ 提前 return / 卫语句
📜

超长参数列表

一个函数传 8 个参数,调用时全靠数逗号

↳ 封装成对象/数据类
🤐

名不副实

函数叫 get_data 却顺手写了数据库

↳ 重命名,让名字说真话
注释##

注释式补丁

大段代码被注释掉「以备后用」,一留三年

↳ 交给 Git 历史,放心删
🎭

万能工具箱

一个 utils.py 塞了三千行,什么都往里放

↳ 按领域拆分模块
🔮

散弹式修改

改一个小需求要动 6 个文件的同一段逻辑

↳ 收拢变化点,单一职责
03

代码评审的
沟通礼仪与流程

  • 评审的本质是「协作」,不是「批判大会」
  • 话术有温度,流程有节奏
  • 新人既要学会「被评」,也要学会「评人」
两位程序员友好评审沟通插画
CH.03 · 礼仪

话怎么说:对事不对人

同一个建议,不同的说法,效果天差地别

🧩
✖ 反面示例「这代码写得也太烂了,重写吧。」
✔ 更好的说法「这个函数挺长,试试把校验逻辑提取成独立函数?可读性会好很多。」
📏
✖ 反面示例「你怎么连 PEP8 都不知道?」
✔ 更好的说法「团队按 PEP8 走,我把 lint 配置和文档发你,跟着跑一遍就 OK。」
❓
✖ 反面示例「这为什么这么写?看不懂。」
✔ 更好的说法「这里用两层循环的原因是什么?如果是性能考虑,换个数据结构会不会更清晰?」
💛礼仪六条:先肯定再建议 · 评论代码不评论人 · 说明「为什么」 · 小问题攒一批提 · 用提问代替命令 · 24 小时内回复评审意见。
CH.03 · 流程

流程怎么走:小步快跑

一次评审的体量越小,质量越高、速度越快

🌿

1. 小分支

一个需求一个分支
PR 控制在 400 行内

➜
🔍

2. 先自查

提交前自己先过一遍清单
别让低级问题浪费评审

➜
📨

3. 发起评审

PR 描述写清「改了什么、
为什么改、如何验证」

➜
💬

4. 讨论修改

评审意见 24~48h 内响应
改完请求复审

➜
✅

5. 合并

达成一致后 Approve
及时合并、删除分支

🚫 必须改(Blocking)涉及缺陷、安全、数据正确性,合并前必须处理
💡 建议改(Suggestion)更好的写法,作者可自行斟酌
❓ 提问(Question)评审人求解释,不一定需要改代码
👍 点赞(Praise)写得好的地方也值得说出来,鼓励新人
04

常用重构手法入门

  • 重构 = 不改功能,只改「代码的结构」
  • 三个最常用动作:提取函数、重命名、消除重复
  • 小步快改,改一步测一步
重组代码积木的重构插画
CH.04 · 手法 ①

提取函数:把「一段话」变成「一个标题」

当代码需要一段注释才能解释时,就该把它提炼成函数了

BEFORE❌ 修改前 · 全挤在一起
def save_user(data): # 校验邮箱是否合法 if not data.get("email") or "@" not in data["email"]: raise ValueError("邮箱不合法") # 姓名清洗:去空格 + 首字母大写 data["name"] = data["name"].strip().title() # 写入数据库 db.execute("INSERT INTO users ...", data) # 发送欢迎邮件 mail.send(data["email"], "欢迎注册")
⚠️ 问题:四件事挤在一个函数里,靠注释分段——注释一过期,逻辑就失明
AFTER✅ 修改后 · 各归其位
def save_user(data): validate_email(data["email"]) clean_name(data) insert_user(data) send_welcome_mail(data["email"]) # 函数名就是「会更新的注释」, # 主流程像目录,每个子函数可独立测试。
✅ 要点:提取时给函数起「说意图」的名字;子函数单独可测,定位问题快得多
✂️什么时候提取:需要写注释解释「这一段在干嘛」时;同一段逻辑出现第二次时;函数超过一屏时。
CH.04 · 手法 ②

重命名:让名字自己说话

好名字省掉一半注释;起名是最便宜的「文档」

BEFORE❌ 修改前 · 猜谜代码
def calc(d, t): return d * t * 0.8 x = calc(5000, 2) # d?t?0.8?x?—— 全靠猜 # 新同事:这是算什么的?🤔
⚠️ 问题:名字没有信息量,每个读者都要重新「破译」一遍
AFTER✅ 修改后 · 见名知义
LONG_STAY_DISCOUNT = 0.8 # 连住折扣 def calc_room_fee(price_per_day, nights): return price_per_day * nights * LONG_STAY_DISCOUNT total_fee = calc_room_fee(5000, 2) # 不用看实现,签名即文档 ✅
✅ 要点:名字回答「是什么/做什么」;单位、含义写进名字,注释只解释「为什么」
🔤起名小抄:布尔用 is_/has_ 开头 · 函数用动词(calc_/send_/validate_)· 避免拼音缩写和单字母(循环变量 i 除外)。
CH.04 · 手法 ③

消除重复 + 重构安全三原则

同一逻辑只写一次,改起来才不会顾此失彼

BEFORE❌ 修改前 · 同一逻辑写两遍
def get_admin_name(user): return (user.last or "") + (user.first or "") def get_user_display(u): # 又写了一遍几乎相同的逻辑 return (u.last or "") + (u.first or "")
⚠️ 问题:格式规则一变(如加分隔符),要记得改两个地方
AFTER✅ 修改后 · 收拢到一处
def get_display_name(user): return f"{user.last or ''}{user.first or ''}" # 管理端、用户端统一调用同一个函数, # 规则变化只需修改这一处。
✅ 要点:发现「似曾相识」的代码,把不变的部分抽成函数,变化的部分做成参数
1️⃣ 小步慢走每次只做一种重构,别把「重命名+搬移+改逻辑」混在一次提交里
2️⃣ 测试兜底重构前后行为必须一致,先有测试再动手,改一步跑一步
3️⃣ 及时提交每完成一小步就 commit,出问题随时回退,绝不「憋大招」
05

新人自查清单

  • 提交代码前,花 5 分钟逐项打勾
  • 清单不是束缚,而是「免费的评审」
  • 坚持一个月,它就会变成你的肌肉记忆
自查清单打勾插画
CH.05 · CHECKLIST

提交前,请逐项打勾 ✅

全部打勾再提评审,你的 PR 通过率会明显上升

🧼代码质量

  • 命名达意:变量、函数「见名知义」,无拼音缩写
  • 无魔法数字:关键数值/字符串已提取为命名常量
  • 函数短小:没有超过一屏的函数,嵌套不超过 3 层
  • 无复制粘贴:相似逻辑已提取为公共函数

🌿提交规范

  • 分支命名符合团队约定(如 feat/xxx、fix/xxx)
  • Commit 信息清晰:说清「做了什么、为什么」
  • PR 描述完整:改动范围 + 验证方式 + 关联任务单
  • 一次 PR 只做一件事,没有「顺手改」的无关文件

🧪测试自测

  • 新代码有对应测试(至少覆盖核心路径)
  • 所有测试本地通过,CI 绿灯
  • 边界情况想过一遍:空值、极端值、并发
  • 手工验证过主流程,不只是「应该没问题」

🤝评审配合

  • 提评审前,自己先完整读过一遍 diff
  • 评审意见 24h 内回复;不认同就摆事实讨论
  • 修改完成后主动请求复审,不要悄悄改
  • 被指出的问题记进自己的「错题本」,同类不二犯
WRAP-UP
代码是写给人看的,
只是顺便能在机器上运行。
🛡️ 审查=质量体检🤝 协作靠规范👃 识别三大坏味道 💬 评审对事不对人✂️ 重构小步快跑📋 清单日日过
→ 本周行动:用自查清单提交你的第一个 PR,并请导师帮你评审一次
01 / 20