Vue项目注释需分层规范：文件头用koroFileHeader（禁用自动时间）、语义标记用Better Comments（按语言隔离）、函数级用VS Code JSDoc命令+手动补全，避免Document This/ESDoc等插件因Vue语法特性失效。
Vue 项目里注释乱、格式不统一、团队看不懂，不是靠插件“自动生成”能解决的——关键在规则分层：文件头用 koroFileHeader，语义标记用 Better Comments，函数级文档用 VS Code 内置 JSDoc 命令 + 手动校验，三者不能混用。
为什么 Document This / ESDoc 在 Vue 项目里基本失效
它们依赖函数签名做参数推导，但 Vue 组件的 setup 函数、defineProps 解构、组合式 API 的 ref/computed 声明，全都不符合传统 JS 函数结构。
-
defineProps({ id: Number, name: String })→ Document This 看不到参数名，生成空@param行 -
const { data } = useApi()→ ESDoc 无法识别useApi返回结构，@returns直接写{any} - 箭头函数写法的
computed(() => ...)或onMounted(() => {...})→ 两个插件均跳过，不触发注释生成 - Vue 单文件组件中
<script setup>没有显式函数名 → 插件找不到“被注释对象”，直接静默
koroFileHeader 配置必须关掉自动时间更新
它默认把 Date 和 LastEditTime 设为 “Do not edit”，但实际会偷偷覆盖你手动填的值，尤其在 Git 合并冲突后导致时间戳错乱。
- 在
settings.json中显式禁用："fileheader.configObj": { "autoAdd": false, "createFileTime": false } -
fileheader.customMade里的Date和LastEditTime字段删掉，改用 Git 提交时间或 CI 构建时间替代 - 如果团队要求记录作者，别填死
"Author": "your name"，改用"Author": "${author}"（VS Code 支持变量注入） - Vue 文件头模板建议只保留：
Brief（一句话说明组件用途）、Version（对应 package.json 的 version）、Copyright
Better Comments 必须按语言隔离启用
Vue SFC 的 <template> 区域是 HTML，<script> 是 TS/JS，<style> 是 CSS —— 同一个注释前缀在不同区块语义完全不同，全局开启会导致误高亮。
vue-composition-api-best-practices
下载
Vue 3 组合式 API 与 最佳实践，涵盖代码组织、useXxx 模式、组合式函数设计、Store 集成、响应式优化及功能抽取。
立即学习“前端免费学习笔记（深入）”；
- 禁用非脚本区高亮：
"better-comments.ignoreLanguageGrammars": ["html", "css", "vue-html"] - 只对
javascript、typescript、vue语言启用："[javascript]": { "better-comments.enable": true }等逐条配置 - Vue 中常用但易冲突的前缀：
// TODO（待实现逻辑）、// HACK（临时绕过响应式限制）、// NOTE（说明watch的 deep 为何设为 true）——这些必须和业务强绑定，不能泛化 - 避免使用
// FIXME：Vue 的响应式失效、nextTick时机问题等，本质是设计理解偏差，不是“要修的 bug”，用// NOTE+ 原因说明更准确
函数级注释唯一可靠路径：VS Code 内置命令 + 手动补全
不要等插件“猜”，而是用编辑器原生能力插入骨架，再根据 defineProps / defineEmits / 返回值类型手填内容。
- 光标停在
setup函数名或defineProps调用行上方，按Ctrl+Shift+P→ 输入Insert JSDoc comment→ 回车，生成基础/** */块 - 对
defineProps，手动补全：@param {Object} props - { id: number, name: string }（类型写具体结构，别写any） - 对
defineEmits，补@event {string} update:modelValue - 触发时机说明 - 返回值若为
Record<string, Ref>，写@returns {Object} { count: Ref<number>, loading: Ref<boolean> }，不缩写 - JSDoc 块必须紧贴声明行，中间**不能有任何空行**，否则 TypeScript 不识别、Volar 不提示、CI 中的
jsdocCLI 直接跳过
真正卡住团队的是注释和代码脱节——比如 defineProps 加了新字段但没更新 @param，或者 emits 类型变更后 @event 还是旧的。这类问题没法靠插件自动发现，只能靠 PR 时人工核对、CI 中加 jsdoc 校验步骤、以及把注释当作接口契约来对待。
