<p>Less注释需区分用途：单行//仅用于开发备注且编译剔除，块注释/ /会进入生产CSS，须避免泄露敏感信息或过期内容；文档注释应规范参数、副作用及设计系统链接，并通过CI校验防止失效。</p>
Less 注释不是“写不写”的问题，而是“怎么写才不翻车”的问题——单行注释被编译剔除，块注释却会原样进 CSS；文档注释没标准写法，团队协作时容易变成“谁也看不懂的自言自语”。
单行注释 // 为什么不能替代块注释 /* */
单行注释 // 在编译后完全消失，适合临时禁用代码或加开发备注；块注释 /* */ 会被保留进最终 CSS 文件，可用于向下游（如后端、测试、运维）传递样式意图。
- 调试时想临时关掉某段 mixin 调用，用
// .clearfix();最安全，不会污染输出 - 要说明某个 class 是为兼容 IE11 特设的，必须用
/* @IE11: requires display: inline-block fallback */，否则上线后没人知道为啥多这一行 - VS Code 或 WebStorm 中快捷键
Ctrl+/默认切换单行注释，容易误用——尤其在嵌套结构里按多了，会导致整块样式被注释掉却毫无察觉
块注释 /* */ 在编译输出中暴露哪些风险
块注释内容照搬进 CSS，意味着它可能出现在生产环境的源码里，带来两类实际问题：泄露内部逻辑、干扰工具解析。
- 不要在
/* */里写敏感路径或变量名，比如/* @import './tokens/secret-vars.less' */—— 这行会直接出现在线上 CSS 中 - 避免使用
/* TODO: refactor after v2.0 */类型标记，构建工具（如 webpack 的 css-minimizer-webpack-plugin）默认不清除注释，上线后用户右键查看源码就能看到 - 若需保留版权头或构建信息，统一放在入口
main.less顶部，且用/*! */（带叹号）写法，多数压缩工具会识别并保留它
Less 命名空间与 Mixin 内部注释怎么写才不误导人
给 .button-variant() 这类 Mixin 加注释，重点不是解释“这是个按钮”，而是说清参数行为边界和副作用。
立即学习“前端免费学习笔记（深入）”；
- 别写
/* 按钮变体混合 */，要写/* @param @bg background color, supports rgba() but not hsl() */ - Mixin 若修改了全局状态（如重置
box-sizing），必须显式标注/* @side-effect resets box-sizing to border-box */ - 命名空间
#theme-dark里定义的变量，注释应指向设计系统文档链接，而不是重复描述颜色值，例如：/* @see https://design.example.com/tokens#dark-mode */
多人协作时最容易被忽略的注释陷阱
注释失效往往不是因为没写，而是因为“写了但没人维护”。最常见的是三类过期注释：
- 变量改名后，旧注释还指着已删除的
@old-primary-color - 组件重构后，注释里写的“仅用于登录页”实际已被复用到注册页和重置页
- 用
/* HACK: force reflow on Safari */临时修复，半年后没人记得 Safari 是否仍需该 hack，也不敢删
真正管用的做法，是在 CI 流程中加入注释校验脚本：扫描所有 /*.less$/ 文件，对含 HACK、TODO、@deprecated 的行触发告警，并强制关联 Jira ID 或 PR 链接——否则注释只会越积越多，越来越不可信。
