<p>HTML模板中只该用<!-- -->注释，其他语法会导致显示异常或解析错误；注释需说明“为什么”和注意事项，位置须与代码同缩进且换行紧贴，禁用内联注释，并通过CI校验过期关键词。</p>
HTML模板里该用哪种注释写法
HTML模板中只该用 <!-- --> 这一种注释语法，其他如 // 或 /* */ 在 HTML 文本节点里不会被解析，反而可能暴露在页面上或引发解析错误。
常见错误现象：有人把 JavaScript 注释习惯带进 HTML 模板，在 <script> 外写 // header section，结果这段文字直接显示在网页顶部；或者在 <style> 块外用 /* reset */，导致样式失效。
-
<!-- header start -->是唯一安全、跨浏览器兼容的写法 - 避免嵌套注释：
<!-- <!-- nested --> -->会提前终止，浏览器只认第一个--> - 不要在
<script>或<style>标签内部用 HTML 注释——那里应分别用//或/* */
团队协作时注释要写哪些信息
模板注释不是写给自己看的，是写给下一个修改它的人看的。重点不是“这里是什么”，而是“为什么这么写”和“改这里要注意什么”。
比如 <!-- sidebar: only shown on desktop, hidden via .sidebar-mobile-only class --> 就比 <!-- sidebar --> 有用得多。
立即学习“前端免费学习笔记（深入）”；
将调研报告、方案对比、数据分析、需求梳理、会议纪要、设计说明、代码评审、学习笔记等任务产物输出为可在浏览器直接打开的单文件 HTML，替代 Markdown 作为最终交付物。Markdown 在信息密度、视觉清晰度和可分享性上已跟不上 AI 产物的丰富度，HTML 能同时承载排版、表格、SVG 等。
- 标明依赖项：
<!-- requires data-user-id attr on <body> --> - 标注条件逻辑：
<!-- rendered only if user.hasSubscription === true --> - 提示样式边界：
<!-- this div must stay outside .container for full-width bg --> - 禁止随意删改的区域加警告：
<!-- DO NOT REMOVE: tracking pixel wrapper -->
注释位置和缩进怎么保持统一
注释必须和它所描述的代码块处于同一缩进层级，且紧贴上方（非内联）。否则 Prettier 或团队格式化工具一跑，注释就飘到错位位置，失去上下文。
错误示例：<div class="card"><!-- card wrapper --> —— 这属于内联注释，难维护、易错位、无法被大多数 lint 工具识别。
- 正确写法是换行+对齐：
<!-- card wrapper --><br><div class="card"><br> <p>content</p><br></div>
- 所有注释前不加空格，后不加空格：
<!-- foo -->✅，<!-- foo -->❌ - 多人编辑时，Replit/CodeSandbox 会把注释当普通文本同步，缩进错位后极易引发合并冲突
自动化检查注释是否遗漏或过期
靠人眼检查注释有效性不可靠。建议在 CI 流程中加一条简单校验：扫描所有 <!-- 后是否紧跟非空格字符，并检查是否存在明显过期关键词（如 TODO、FIXME、old logic）。
一个最小可行脚本：grep -n "<!--.*TODO\|FIXME\|old" src/**/*.html，把它放进 pre-commit hook 或 GitHub Actions。
- 别指望注释永远准确——它们和代码一样会腐烂。定期 grep + 人工抽查比写满注释但没人维护更可靠
- 如果某个模板区块连续三个月没人动过，但注释里还写着“临时方案”，大概率已经变成事实标准，这时该删注释，补文档
- CodeSandbox 的 Git 集成分支里，注释变更不会触发自动测试，得靠人盯——这点最容易被忽略
