<p>SCSS 文件级注释必须用 / / 且含 #xxx 锚点，紧贴代码块上方、后跟唯一空行；@mixin/@function 需 /* / 注释说明契约；变量须语义化分层管理；锚点名称须全局一致。</p>
SCSS 文件级注释必须用 /* */，且含 #xxx 结构锚点
文件开头不写注释，或只写“按钮样式”这类空泛描述，等于关掉了团队成员的导航开关。VS Code 和 Vim 都支持 # 锚点跳转——光标停在 #form 上按 # 键，直接落到对应代码块。但前提是：必须用 /* */（不能用 //），每行以 * 开头，结尾单独一行 */，锚点统一为 #xxx 格式。
常见错误现象：// 表单模块 这类单行注释在编译后消失，无法被文档生成器（如 Styleguidist）识别；/* #form */ 写在代码块中间，而非紧贴其上方，导致跳转失效。
-
/* #form */必须与后续第一个选择器之间有且仅有一个空行 - 锚点名称需与文件级注释中列出的结构完全一致，大小写、连字符都不能错
- 禁止在嵌套规则内部加
#锚点，比如&:hover { /* #hover-state */ ... }会破坏层级语义
@mixin 和 @function 的注释必须说明契约，而非行为
一个没注释的 @mixin button-size($size) 就是定时炸弹。别人传入 sm 却得到意外的 padding 值，问题可能出现在三个月后的某个 PR 里。注释要回答三个硬问题：怎么调？什么会变？什么不能动？
实操建议：
立即学习“前端免费学习笔记（深入）”；
- 每个
@mixin或@function前必须跟/** */块注释，禁用行尾注释 - 用
@param $size明确类型与取值范围，例如：@param $size — 尺寸枚举值，可选 sm/md/lg，非数字 - 用
@return说明返回值（@function必写）；用@warning标明副作用，如“修改:root变量，影响全局 z-index”
代码块之间必须用空行 + #xxx 分隔，不可省略
没有空行的 SCSS 文件，视觉上就是一堵墙。人眼无法自然识别逻辑边界，审查 PR 时容易漏掉某段样式变更。空行不是为了“好看”，而是强制划分作用域——配合 #xxx 锚点，才能让搜索 #table 直接落到表格样式区，而不是在一堆嵌套里手动翻找。
典型踩坑点：
- 把多个功能块（如
.modal-header、.table-responsive）挤在同一个代码块里，中间无空行 -
#xxx名称与文件级注释中声明的结构锚点不一致，比如注释写#layout，实际代码前却写/* #Layout */ - 临时 hack 没加专属锚点，例如修复 iOS 17.4 的 bug，应写
/* #hack-ios-17-4 */并附带失效条件说明
变量命名必须语义化，!default 要慎用
把颜色值硬编码进每个选择器里，等于主动放弃维护权。改个主色要搜遍所有 .btn-primary、.header-bg 去替换 #007bff，这种事每天都在发生。SCSS 变量不是装饰品，是统一控制点。
关键差异点：
- 用
$color-primary而非$blue-500——设计系统换色后，后者立刻失效 - 变量文件应分层拆分：
_variables.scss（基础值）、_theme.scss（主题映射）、_tokens.scss（设计 token 映射），避免单文件膨胀 -
!default在多层@import下会让覆盖逻辑隐晦，建议只在基础库中使用，业务层显式重赋值
最常被忽略的其实是锚点一致性：文件级注释里的 #form、代码块前的 /* #form */、Git 提交信息里的 feat(form): add validation——这三处名称一旦错位，整个导航链就断了。
