bem注释必须紧贴css中.block类定义，不可置于html或js内；常见错误是将注释写在html的class属性旁，如。
注释必须紧贴 .block 类定义，不能放在HTML里或JS中
很多人把BEM注释写在HTML的class属性旁，比如<div class="card">
<!-- 卡片模块：展示商品摘要与操作按钮 -->，这会导致样式逻辑和结构耦合，一旦重构HTML就丢失上下文。真正有效的注释要和CSS声明绑定，确保开发者打开SCSS文件就能立刻理解这个<code>card是干什么的。
推荐写法是：在每个.block规则上方用块注释说明功能边界、复用场景和关键约束：
/**
* card — 商品卡片模块
* 功能：聚合商品图、标题、价格、操作按钮，支持横向/纵向布局切换
* 复用条件：独立存在，不依赖父容器语义（如不能只在 product-list 下生效）
* 约束：不设置 margin；不使用 position: absolute；所有 modifier 仅作用于自身节点
*/
.card { ... }
block__element 不需要单独注释，但需在 .block 注释中列出关键子元素
BEM强调“element 是 block 的组成部分”，不是独立单元，所以给.card__title单独加一段注释属于冗余。真正重要的是让阅读者一眼看出哪些子元素构成该 block 的完整能力。
在.block的主注释末尾用列表式说明即可，避免遗漏关键部分：
-
card__image：必须存在，用于渲染商品主图，支持懒加载 -
card__price：可选，若不存在则隐藏价格区域，不触发重排 -
card__actions：必须存在容器，内部按钮由业务层决定（加入购物车 / 立即购买）
这样既控制注释密度，又明确 element 的职责边界——不是“这个类干嘛”，而是“这个 element 在 block 中承担什么角色”。
修饰符 --modifier 的注释必须包含触发条件和副作用范围
常见错误是只写/* 暗色主题 */这种模糊描述。BEM中.card--dark实际影响的是背景、文字、边框三处颜色值，且**不会改变card__image的滤镜或card__actions的悬停行为**——这些细节必须写进注释，否则后续维护者可能误以为 modifier 具有穿透性。
正确写法示例：
/**
* .card--dark
* 触发条件：用户系统偏好为 dark mode，或页面级 theme="dark"
* 影响范围：仅修改 .card 节点的 background-color / color / border-color
* 不影响：.card__image（保持原图）、.card__actions:hover（仍用默认高亮色）
*/
.card--dark { ... }
禁止在注释里出现“容器”“区域”“模块”这类空泛词
像/* user-info 区域 */或/* 导航容器 */这种注释等于没写。BEM的block必须是功能实体，注释要回答“它做什么”，而不是“它在哪”。
检查清单：
- 是否用了名词命名？
user-avatar✅，top-nav❌（含位置） - 是否说明了输入/输出？例如
search-form要注明“接收关键词，提交至 /api/search” - 是否标注了外部依赖？比如
payment-button需注明“依赖 global.paymentSDK 初始化完成”
注释不是装饰，是契约。一旦user-avatar开始承担头像裁剪+上传+编辑三件事，注释就必须同步更新，否则就是误导。
