4.1 代码规范与可维护性
4.1 代码规范与可维护性
本节摘要：代码规范的价值不是美观，而是把"读懂代码的成本"压到最低——半年后的你、新入职的同事、评审者，都是规范的受益人。本节讲最小规范集（格式、命名、语义优先、注释纪律）、自动化工具链如何让规范零成本执行，以及可维护性的三个可操作判据。
学习目标
阅读完本节，你应当能够：
- 论证规范的价值主张，回应"规范浪费时间"的质疑；
- 制定一份最小 HTML 规范集并说明每条的依据；
- 配置格式化与检查工具，让规范自动执行；
- 用三个判据评估一段标记的可维护性；
- 识别五种最常见的可维护性坏味道并给出修法。
规范到底在优化什么
先回应一个真实存在的质疑："规范是形式主义，能跑的代码才是好代码。"这个说法错在把代码的读者搞错了。代码写完的那一刻起，它最主要的读者就不是编译器（编译器什么都忍），而是三个月后改这段代码的人——多半就是你自己。统计数据反复显示，工程师花在"读代码"上的时间远超"写代码"，规范的全部目标就是把读的成本压下来：统一的缩进让结构一眼可辨、统一的引号消灭无意义的心智切换、统一的命名让"找定义"变成肌肉动作。
规范不创造功能，它降低协作摩擦与变更成本。换个角度算账：一份混乱的页面文件，新人接手要读半小时才知道改哪；规范的页面五分钟定位。乘以项目生命周期里几百次的修改，规范省下的时间比制定规范花的几分钟高出两三个数量级。这也是为什么成熟团队宁可花一周争论缩进用空格还是制表符（争论完自动统一，永不再议），也不愿十年里每个新人各自带来一套风格。
最小规范集
不需要一部百科全书式的规范手册，一份能贴在墙上的最小集就够用。我给出建议版本，每条附依据：
格式四条：缩进统一两空格（HTML 嵌套深，两空格省横向空间）；属性值一律双引号（第 1 章讲过无引号的注入风险）；布尔属性裸写；每行控制在可读宽度，属性过多时一个属性一行。
命名三条：类名描述"是什么"不描述"长什么样"（card 而非 red-big-box，改版时类名才不会撒谎）；多词用连字符（user-card，与 CSS 的连字符传统一致）；data-* 前缀承载自定义数据，不自造属性。
结构五条：每个页面一个 h1、层级不跳号（第 2 章）；div 与 span 是最后选项（写前先问那句"有没有语义元素"）；label 必须关联控件；图片必须有 alt（哪怕值为空）；视频音频必须有降级内容。
注释两条：注释解释"为什么"不解释"是什么"（第 1 章的三条禁忌）；将被注释掉的代码直接删除，版本控制记得一切。
十二三条，覆盖日常九成场景。要强调的是：规范集本身可以自定义，但必须唯一——团队里两套规范并存，比没有规范更糟，因为读代码的人要先识别"这是哪套风格"。
工具链：让规范自动执行
规范靠自觉必败，靠工具必成。现代前端的规范执行已经完全自动化，两个角色分工明确：
格式化工具（如 Prettier）：一键把代码排成统一格式，缩进引号换行全自动。它的哲学是"不给你选择"——团队只需要约定两空格加双引号两个参数，剩下交给工具。从此评审里再也不会出现"这里少缩进"式的外观意见，评审注意力全部留给逻辑与结构。
检查工具（如 HTMLHint、stylelint 之于样式）：按规则扫描并报错，比如"img 缺 alt""id 重复""有重复属性"。检查工具接进持续集成（第 5 章工程化话题），提交即检查，违规即拦截，规范从"文档里的约定"变成"流水线上的门禁"。
<!-- 工具链的输入：随手写的混乱代码 --> <div class=user-card id='card1' > <img src=avatar.png> <span style="color:red;font-weight:bold" class="text">VIP 用户</span></div> <!-- 格式化与检查之后：同样内容，规范形态 --> <div class="user-card" id="card1"> <img src="avatar.png" alt="用户头像"> <span class="user-card__badge">VIP 用户</span> </div>
对比里藏着工具做对的三件事：补齐引号、把内联样式迁出（检查规则可配置"禁止 style 属性"）、提示补 alt。把这段对比反过来读也成立——规范清单里的每一条，都应该是某个工具规则能自动检查的，检查不了的条款（比如"类名要有业务含义"）才需要人评审。工具管机械的，人管意义的，这条分工线就是规范落地的全部秘密。
可维护性的三个判据
"可维护"是个模糊词，拆成三个可操作的判据就清晰了：
判据一：定位速度。 给一个新同学（或半年后的你）一个需求"把这个按钮的文案换掉"，多久能找到该改哪一行？语义结构、稳定命名、合理拆分决定这个速度。定位超过五分钟，就是结构信号。
判据二：变更半径。 改一个需求，要动几个文件、几处代码？改动半径越小越可维护。改动半径大的典型成因是复制粘贴的重复块——同一张卡片复制了八处，改版要改八次。解法是组件化或至少模板化（第 5 章的主题），HTML 层面则是"结构与样式复用类名、行为复用数据属性"。
判据三：删除难度。 下线一个功能时，能不能干净删掉？删不干净的功能会留下"尸体代码"——没人敢动的注释块、无处归属的样式规则、不知服务谁的脚本。定期做删除演练（尝试移除一个模块看会坏什么），尸体代码的积累速度就能控制住。
五种坏味道与修法
<!-- 坏味道一：div 万物皆可装 --> <div class="button" onclick="submit()">提交</div> <!-- 修法：换成原生 button，免费获得键盘与语义 --> <!-- 坏味道二：类名编码外观 --> <div class="margin-top-20 red-text bold">警告</div> <!-- 修法：类名改述语义 .alert，样式进样式表 --> <!-- 坏味道三：内联样式硬编码 --> <p style="font-size:14px;color:#333">正文</p> <!-- 修法：进样式表随全局字号体系缩放 --> <!-- 坏味道四：被注释掉的代码块 --> <!-- <div class="old-banner">春季活动</div> --> <!-- 修法：删除，历史交给版本控制 --> <!-- 坏味道五：一行塞尽 --> <div class="card" id="c3" style="..." data-x="1" onclick="..." title="...">…</div> <!-- 修法：属性分行，行为迁出标记 -->
五种坏味道的共同病根是**"现在方便"对"以后方便"的透支**。写的时候省了十秒，每个后来者每次都要多花一分钟。规范与工具链的本质，就是用十秒的自动化成本，买断未来的重复损耗。
动手实验：给一份页面做规范体检
<!DOCTYPE html> <html lang="zh-CN"> <head> <meta charset="UTF-8"> <title>规范体检样本</title> </head> <body> <div class="header"> <div class="big-title">体检样本站</div> <div class="menu"> <span onclick="location='home.html'">首页</span> <span onclick="location='about.html'">关于</span> </div> </div> <div class="content"> <div class="item" style="color:#c0392b;font-weight:bold">重要通知：明天维护</div> <img src="chart.png"> <!-- <div class="old">旧版通知</div> --> </div> </body> </html>
拿这份"祖传样本"按本章清单逐条体检：h1 缺失（big-title 是伪标题）、菜单用了 span 加行内脚本而不是链接加 nav、重要通知用内联样式表达严重性（改用语义类）、图片缺 alt、注释块是尸体代码。每找到一处，按第 2 章的改造三步法修掉。修完你会发现：这份体检同时是第 2 章、第 3 章与本节的总复习——规范从来不是孤立的题，它是前三章知识的纪律化。
💡 关键直觉：规范的最高境界是"消失"——当工具自动执行一切机械条款，团队只在评审里讨论结构与语义，规范就不再被感知，它成了空气。
规范的团队落地路径
个人写规范是习惯问题，团队推规范是政治问题——总有人觉得自己的风格更好，总有人嫌工具麻烦。落地路径三步，每步都有明确目的。
第一步，先上工具后开会议。格式化工具的配置十分钟搞定，先让所有新代码自动统一。这个顺序很关键：工具统一了机械条款之后，剩下的讨论空间就只剩结构与语义——那些真正值得人讨论的问题。反过来先开会争论缩进，会议会消耗掉团队对"规范"这个词的全部好感。
第二步，规范写进项目而非文档。配置文件跟着代码库走，新成员克隆项目即获得全部规范环境，不需要阅读任何"入职文档"。检查规则挂在提交流程上，违规进不了主干。规范的最高形态不是一份人人签过字的手册，而是一套不存在感很强的自动化环境。
第三步，例外要有出口。任何规范都会遇到不适用场景（历史代码、第三方约束），硬套会导致荒谬结果。给出路：例外需要注释一行原因，评审认可后放行。有出口的规则才守得住，没有出口的规则会被整体绕过——这与管理系统的道理相通，阻塞的通道会催生地下通道。
<!-- 例外的标准形态：一行注释说清原因与期限 --> <!-- 保留内联样式：邮件客户端环境无法引用样式表，见第2章多媒体节 --> <div style="font-family:sans-serif">...</div>
高频疑问两则
问：个人小项目要不要讲规范？
要，但目的不同。团队项目讲规范是为了协作，个人项目讲规范是为了"未来的自己"——三个月后的你相对今天的你就是一位新同事，判据一二三同样适用。且个人项目是练习规范肌肉记忆的最好场合，习惯带进团队零成本。
问：规范和代码风格是同一回事吗？
风格是规范的子集。格式（缩进引号）是风格，交给格式化工具；结构约定（语义优先、label 关联）与命名约定超出风格范畴，需要检查工具与评审共同守护。把两者混为一谈的团队常犯两类错误：要么用格式化工具覆盖一切（结构问题漏网），要么用人力检查一切（浪费在缩进上）。
问：规范会不会限制创造力？
限制的是表达形式的随意性，不是解决方案的多样性。恰恰相反，统一的底座让创造力花在刀刃上：没人会觉得"统一用简体中文写作"限制了文章的思想，代码同理。真正消耗创造力的是每次接入新模块都要先逆向工程上一任的风格——规范消灭的正是这种无谓消耗。
本节要点回顾
- 规范优化的是读代码的成本：主要读者是未来的修改者，不是机器。
- 最小规范集十二三条：格式四条、命名三条、结构五条、注释两条；条款可自定义但必须唯一。
- 工具管机械的、人管意义的：格式化一键排版，检查工具做门禁，评审只看结构与语义。
- 可维护性三判据：定位速度、变更半径、删除难度——模糊概念拆成可操作指标。
- 五种坏味道同根：现在方便透支以后方便，规范就是买断这笔负债。
- 落地三步：先上工具后开会议、规范写进项目而非文档、例外留注释出口。
下一节进入机器维度：当读你页面的不是人而是读屏软件，质量意味着什么。