BEM类名自带语义，可替代三类注释：“组件归属”“DOM层级限制”“状态说明”；但非直观兼容、跨端联动、临时hack及Modifier隐含约束仍需注释。
直接说结论：BEM本身不写注释，但类名自带语义，card__title--warning 比 h2.red 更容易让人秒懂用途，自然就少写甚至不用写 CSS 注释。
为什么类名能替代部分 CSS 注释
BEM 把结构关系、层级归属、状态含义全塞进类名里，浏览器不关心你有没有注释，它只认类名是否匹配——而人眼扫一眼类名，就能还原出“这是卡片里的标题，当前是警告态”。传统写法里 .title-red 这种命名，得靠注释说明“用于错误提示的标题”，而 form-field__label--error 自己就说清了。
- 类名即上下文：
header__logo不用注释“这是页头的 logo”，user-avatar__initials也不用解释“显示用户首字母” - Modifier 直接表达状态：
button--disabled比.btn[disabled]+ 注释“禁用态样式”更可靠，因为后者依赖 HTML 属性存在，前者只要加了类就生效 - Element 名强制聚焦角色而非样式：
search-form__clear明确是“清空按钮”，不是btn-icon这种靠注释才能猜用途的泛称
哪些注释可以安全删掉
团队落地 BEM 后，以下三类 CSS 注释大概率可删，且不会影响后续维护：
- “这个样式属于 XX 组件”——类名里已有
product-card__price，无需再写/* 产品卡片价格 */ - “该元素在 XX 容器下才生效”——BEM 不依赖 DOM 层级，
.sidebar__item不会因挪到.main下就失效，不用注释“仅限侧边栏使用” - “此样式用于禁用态”——
input--disabled已含状态语义，不必额外加/* 禁用时隐藏边框 */
但别误以为“完全不用写注释”
BEM 解决的是“类名意图模糊”问题，不是“所有逻辑都自解释”。这些地方仍需注释：
立即学习“前端免费学习笔记（深入）”；
- 非直观的视觉妥协：
/* 为兼容 Safari flex gap，额外加 1px margin-top */ - 跨组件联动逻辑：
/* 与 JS 的 data-state="loading" 同步，避免样式/行为不一致 */ - 临时 hack 或待修复项：
/* TODO: 移除，待 antd v5.12 支持 CSS vars */ - Modifier 的隐含约束：
/* 注意：card--featured 必须配合 card__image 使用，否则布局错位 */
真正难的是让团队所有人写出语义清晰的 Element 名——比如把 user-card__delete-btn 改成 user-card__action--delete，这种细节没人盯就容易退化。类名一旦带行为动词或样式词（big、left），自注释能力立刻打折扣。
