SCSS 文件级注释必须用 /* / 且含 #xxx 结构锚点，代码块间需空行分隔并复现对应锚点；模块级注释须明确 @mixin/@function 的参数、返回值与契约；行内注释仅解释 why，用 // 紧贴代码右侧。
SCSS 文件级注释必须用 /** */，且含结构锚点
SCSS 文件开头不写 /** */ 注释，或只写空泛描述，会导致团队成员无法快速定位模块。文件级注释不是可选项，而是导航入口。
关键点在于用 # 做结构锚点：它既符合 CSS 注释语法，又能在 Vim/VS Code 中通过 # 快速跳转（光标停在 #list 上按 # 键即可跳到对应代码段）。
- 必须以
/**开头，不能用//（后者编译后消失，无法用于文档生成） - 每行注释内容前保留
*（星号+空格），结尾用*/单独一行 - 结构锚点统一用
#xxx格式，如#reset、#layout、#form，并在实际代码块前复现同一锚点 - 避免写 “样式文件”“按钮相关” 这类无信息量描述；要说明用途边界，例如：
/** * 仅用于弹窗内表单控件，不兼容 inline-block 容器 */
模块级注释要说明 @mixin / @function 的契约
一个 @mixin 如果没注释清楚参数含义、默认值、副作用和调用约束，就等于埋雷。尤其当它被跨项目复用时，错误传参可能引发难以追踪的布局错位。
模块级注释不是写作文，而是定义接口契约。重点回答三个问题：怎么调？什么会变？什么不能动？
立即学习“前端免费学习笔记（深入）”；
- 每个
@mixin或@function前必须跟/** */块注释，禁止行尾注释 - 用
@param $name明确类型与含义，例如：@param $size— 尺寸枚举值，可选sm/md/lg，非数字 - 用
@return说明返回值（对@function必须写）；用@see关联依赖项，如@see $z-index-modal - 若该 mixin 会修改全局状态（比如注入
:root变量），必须加@warning提示
CSS 代码块之间必须用空行 + #xxx 锚点分隔
没有空行的 SCSS 文件，视觉上就是一堵墙。人眼无法自然识别逻辑边界，审查 PR 时容易漏掉某段样式变更。
空行不是为了“好看”，而是强制划分作用域。配合 #xxx 锚点，才能让“搜索 #table”直接落到表格样式区，而不是在一堆嵌套里手动翻找。
- 每个功能区块（如
.modal-header、.table-responsive）前插入一个空行 +/* #table */行 -
#后名称需与文件级注释中列出的结构锚点完全一致，大小写和连字符都不能错 - 禁止在嵌套规则内部再加
#锚点（例如&:hover下不写/* #hover-state */），这会破坏层级语义 - 如果某段样式是临时 hack（如修复某个 iOS 版本 bug），必须写
/* #hack-ios-17-4 */并附带失效条件说明
行内注释只能解释 why，且必须与代码同行
写 // 改成 flex 是因为 Safari 15.6 不支持 grid subgrid 是有效注释；写 // 设置宽度 是噪音。
行内注释的价值在于记录决策依据，而不是复述代码。一旦它开始解释 how，就说明这段逻辑本身已超出合理复杂度，应该拆成 mixin 或提取变量。
- 只允许用
//，且必须紧贴代码右侧，前面留两个空格，例如：display: flex; // Safari 15.6 不支持 subgrid - 禁止在声明末尾加
!important后补注释，应提前在块注释中说明覆盖理由 - 当同一组属性需要统一解释时，优先提升为块注释，而非重复写多行
// - 所有涉及浏览器兼容性、设计系统约束、A/B 实验标识的判断，都必须出现在行内注释中，不能只靠口头同步
真实项目里最常被忽略的，是文件级锚点与代码块锚点的名称一致性和空行强制性。少一个空行，Vim 搜索就会跳过下一块；锚点拼错一个字母，整个导航体系就失效。这不是格式洁癖，而是降低每次 git blame 成本的实际手段。
