5.1 代码规范与版本控制：交接班手册

5.1 代码规范与版本控制：交接班手册

本节摘要：代码规范是三班共用的书写约定，让任何人接手任何文件都不用重新学一套方言；版本控制给每次改动记台账——改了什么、为什么改、随时可退。本节给看板代码做一次规范体检，再用版本台账管理看板的三次功能迭代，并在最后埋一次"改坏了"的事故，演练回退。

一、规范的价值：写得让人接得住

第 2 章到第 4 章，看板由三班接力建成。想象半年后来了位新同事接手：结构文件里类名一时叫统计数据一时叫概览数字、样式文件缩进忽宽忽窄、脚本文件既有一行八个语句也有八行一个语句的——接手成本瞬间超过重写。规范的存在不是审美洁癖，是把"阅读成本"从每次接手时重复支付，变成一次约定终身有效。

规范的内容不神秘，无非四类：命名（类名小写短横线、变量函数小驼峰、常量大写）、格式（缩进两格、行宽有限、括号位置统一）、结构（文件头有说明、函数有注释、区块有分隔）、禁则（不用全局变量、不写魔法数字、不裸奔拼接标记）。团队通常直接采一份现成规范加少量定制，配一个自动格式化工具（1.4 节装过的那件）——机器管格式，人管命名与结构。

// 规范体检：同一函数的两种写法对照
// 待检（能跑但难接手）：
function q(o){let r=0;for(let i=0;i<o.length;i++){if(o[i].s=="urgent")r+=o[i].q}return r}
// 问题清单：名字不可读、单行塞满循环、缩进无、宽松相等、魔法字段名

// 过检（体检后）：
/** 汇总加急工单的总数量 */
function sumUrgentQty(orders) {
  let total = 0;
  for (const order of orders) {
    if (order.priority === PRIORITY_URGENT) {
      total += order.qty;
    }
  }
  return total;
}
// 动过的每一处：可读命名、取项循环、严格相等、常量替代魔法串、说明注释
​

看板代码规范体检单（逐文件过）：
- 命名：类名短横线小写、变量函数小驼峰、常量全大写 —— 抽查十个名字
- 格式：保存时自动格式化已开、无超长行、缩进统一
- 结构：每个文件头部一句话说明职责、导出函数有注释
- 禁则：无全局泄漏（都收在模块里）、无魔法值（色板与状态名入常量）
- 三班一致性：同一概念在三份文件里叫同一个名字
  （状态徽章类名、工序选项值、存储键名逐一对表）
​

二、版本控制：给每次改动记台账

版本控制系统的核心模型简单到可以画在纸上：一个仓库存着项目的全部历史，历史由一次次提交串成，每次提交是那一刻全部文件的快照加一句说明。它的三个日常动作：提交（把当前改动记成一页台账）、查看差异（这页台账改了哪些行）、回退（把文件恢复到某一页）。多人协作时再加分支（各改各的互不干扰）与合并（把两条线并回来）——看板暂时单人施工，先把单人动作练熟。

看板的三次功能迭代（用版本台账管理的真实节奏）：

第一页 台账：结构班交付
  说明：搭建看板骨架——文档结构、表格表单、语义化布局
  内容：入口页面与全部结构标记

第二页 台账：样式班交付
  说明：完成装修——色板、卡片、布局机械、响应式适配
  内容：样式文件全量、结构的类名挂点补齐

第三页 台账：行为班交付
  说明：接线通电——数据层、渲染投影、事件闭环、本地存储
  内容：脚本文件全量

每页台账的意义：任何时刻可查"这个功能是哪页引入的"，
任何一页可回退"恢复到当时的状态"。
​

提交说明的写法（台账的字迹要求）：

合格示例：
  新增：工单推进的加急巡检提醒
  说明：advance 后若为加急在制，打点提醒；含两处测试数据更新

不合格示例一：改了点东西
  ——三个月后没人知道改了什么，等于白记
不合格示例二：一次提交混入格式化全文 + 功能改动 + 临时调试代码
  ——一页台账三种账，回退时无法只退功能

写法三问：改了什么、为什么改、影响哪里。三问答完，说明自然合格。
​

两份台账演示的是"怎么记"，动手频率更重要：小步提交——每完成一个可验证的小改动就记一页，而不是攒三天记一页大杂烩。小步台账让"改坏了"永远只坏一页，回退成本最低。

三、事故演练：改坏了怎么回退

规范的演练场来了。场景：你给看板加"批量推进"功能，改了三处，结果页面的单条推进坏了——点击无反应。没有版本台账时，你要凭记忆翻找三处改动的每一行；有台账时，流程是固定的：先看未提交的差异（这页还没记的改动全部高亮），逐块审读定位嫌疑；嫌疑确认后两种修法——改动不大就地修复再记一页新台账；面目全非则回退到上一页完整状态，重来。

事故处置流程（对照演练）：

第一步：查未提交差异
  发现脚本文件里事件委托的目标辨认条件被改动：
  原条件认状态按钮，新条件多加了批量模式的类名判断，
  单条按钮因此被漏判——嫌疑锁定

第二步：评估修法
  就地修复：把类名判断改回包含关系，一行改动，值得就地修
  回退重来：若三处改动纠缠难解，整页回退上一台账，重写更干净

第三步：补记台账
  修复：恢复单条推进的目标辨认
  说明：批量模式的类名判断误伤单条按钮，改为包含式判断

第四步：复盘入规范
  "改事件辨认条件必须回归测试单条与批量两条路径"
  写进团队的检查清单——事故才真正变成资产
​

// 事故现场的技术还原：被误改的辨认条件
// 事故版（单条按钮被漏判）：
const btn = e.target.closest("button.status-btn.exclusive");
// 类名要求过严：单条按钮没有 exclusive 类，closest 返回空 → 无反应

// 修复版（包含式判断，两类按钮都认）：
const btn = e.target.closest("button.status-btn");
// 基础类辨认：单条与批量按钮都带基础类，各自的功能在处理器内分支
​

演练里的第四步值得强调：团队里值钱的不是"从不犯错"，而是"每个错误都沉淀成检查清单的一条"。规范本身就是这么长出来的——它不是天上掉下的教条，是前人踩坑的结晶。

⚠️ 常见坑：台账只在本机记，从不推到远端。硬盘一坏全部历史蒸发，协作更无从谈起。养成"当日台账当日推远端"的习惯，远端仓库同时就是异地备份。

💡 关键直觉：把每次提交想成给当前状态拍快照——快照不值钱，值钱的是"任何历史时刻都可重返"。这个安全感会改变你写代码的胆量：敢大改、敢实验，因为退路永远在。

本节要点回顾

• 规范四类：命名、格式、结构、禁则，机器管格式、人管命名与结构；
• 规范动机：阅读成本一次约定终身摊销，接手成本是重写成本的镜像；
• 台账模型：仓库存历史、提交是快照、差异可审、历史可回；
• 小步提交：一个可验证的小改动一页账，攒大账是回退时的灾难；
• 说明三问：改了什么、为什么改、影响哪里，三问答完字迹自然合格；
• 事故资产化：每个错误沉淀成检查清单一条，规范由此生长。

台账立好了，下一节照顾厂里的老设备：兼容性与补齐策略。