商品详情页需用结构化注释，因其模块易膨胀、协作需快速定位；必须成对标注高变更/高耦合/高依赖区域，禁用过期说明、实现细节与中文标点。
商品详情页为什么要用结构化注释
因为商品详情页是电商项目里最易膨胀的 HTML 模块：轮播图、SKU 选择器、参数表格、详情图文、客服浮层、推荐商品……十几个功能区堆在一起，不加注释，连自己三天后都难定位 price-display 是在哪个 section 里。更关键的是，毕业设计答辩或团队交接时，老师/同事一眼看到 <!-- PRODUCT PRICE SECTION START --> 就知道这块管什么，而不是靠猜 div:nth-child(7)。
注释必须包含起始和结束标记
只写 <!-- SKU SELECTOR --> 是不够的。浏览器不报错，但人容易漏看“结束点”，导致后续代码被误认为还在 SKU 区域内。真实协作中，90% 的“样式错位”“JS 绑定失效”问题，源头都是区块边界模糊。
正确写法必须成对出现：
<!-- ============================== SKU SELECTOR START ============================== --> <div class="sku-selector" data-product-id="1024"> <select name="color"><option>黑色</option></select> <select name="size"><option>M</option></select> </div> <!-- ============================== SKU SELECTOR END ================================ -->
- 用等号围住文字，视觉上形成“隔离带”，避免和内容标签混淆
-
START/END全大写 + 明确模块名，方便搜索跳转（VS Code 里 Ctrl+F 搜SKU SELECTOR END直达） - 模块名用英文全大写+空格，不加下划线或驼峰，比如
PRODUCT DESCRIPTION START，不是productDescStart
哪些地方必须加注释，哪些可以省略
不是所有代码都要注释。过度注释反而干扰阅读。重点覆盖三类高变更、高耦合、高依赖区域：
生成可在 deepbi 沙箱 iframe 内运行或作为独立文件运行的交互式 HTML 页面，使用 `window.deepbi` JS SDK 实现数据查询、空间管理、文件浏览及用户操作。当用户提出以下需求时启用该能力： - 创建 KPI 仪表盘、数据表格、文件浏览器、成员列表、管理页面； - 明确要求“转成 dhtml”、“转译成 HTML”、“把 XX 页面转成……”、“控制台页面”、“管理后台”、“DeepBI 页面迁移”； - 提及位于 `apps/console/src/featur
立即学习“前端免费学习笔记（深入）”；
- 所有含 JS 交互逻辑的容器：如
<div id="cart-add-btn"> 外层必须包 <code><!-- ADD TO CART BUTTON WRAPPER START --> - 动态渲染区块：比如用
data-product-id驱动的参数表格，即使只有 3 行 HTML，也要标注<!-- TECHNICAL PARAMETERS TABLE START --> - 第三方嵌入区：客服组件、评论插件、分享按钮等外部脚本挂载点，必须注明来源与用途，例如
<!-- JIANGHU CUSTOMER SERVICE WIDGET START (v2.1) --> - 可省略的：纯静态文案段落（
<p>本商品支持7天无理由退货</p>）、单行图标<i class="icon-cart"></i>、基础语义标签如<header></header>或<footer></footer>（除非它们内部有复杂嵌套） - 写过期说明：比如
<!-- 旧版价格显示，2025年已停用 -->—— 这种代码应该直接删，留着只会误导人 - 写实现细节：如
<!-- 用querySelectorAll获取所有规格项 -->—— JS 实现会变，但区块职责不变，注释应聚焦“做什么”，而非“怎么做” - 写中文标点混排：避免
【商品标题区】或—— 参数表格开始 ——，统一用英文符号和空格，保证跨编辑器显示一致 - 把注释当 TODO：如
<!-- TODO: 后续接入库存API -->—— 这类任务应进 issue 系统，HTML 注释里只保留当前有效结构信息
注释里不能写什么
注释是给开发者看的，不是写文档。以下内容会降低可维护性，务必避开：
最常被忽略的一点：注释本身也是代码的一部分，要随 HTML 结构同步更新。删掉一个 section，对应注释块必须一起删，否则残留的 END 标记会让后来者以为下面那段代码还属于它。
