Vue3项目注释

vue3项目注释，使用 /** 关闭对话框 */ 还是 // 关闭对话框 哪种好？

在 Vue 3 项目中，选择/** */（JSDoc 风格）还是//（单行注释）取决于注释的用途和受众：

• // 单行注释
  适合用于代码内部的简短说明、TODO、调试标记或解释某行代码的逻辑。它不会被工具提取，仅供开发者阅读，轻量且灵活。

• /** JSDoc 注释 */
  适合用于公共 API的说明，例如：

  • 组件的props、emits、expose的方法

  • 可复用的函数、类的定义

  • 需要生成文档或 IDE 悬停提示的部分

  JSDoc 注释可以被 TypeScript、Volar、Vuese、TypeDoc 等工具解析，为开发者提供智能提示和自动生成文档的能力。

建议

• 组件内部私有函数/变量（如handleClose、filterDept）使用//注释即可，简洁且不干扰文档生成。

• 组件对外暴露的 API（如defineEmits中的事件、defineProps的属性、通过defineExpose暴露的方法）应使用/** */注释，方便使用者理解。

例如，在之前的CapitalAllocateDialog组件中：

typescript

const emit = defineEmits<{ /** * 更新对话框可见性 * @param visible - 新的可见状态 */ (e: "update:visible", visible: boolean): void; /** * 确认分配 * @param allocateData - 分配数据列表 */ (e: "confirm", allocateData: CapitalAllocateCreateDTO[]): void; }>();

这里的 JSDoc 注释是必要的，因为emit是组件的公共接口。

而内部的onAddDetail函数：

typescript

// 增加分配明细 const onAddDetail = () => { ... };

用单行注释就足够清晰。

总结

没有绝对的“好”，但遵循对内用单行，对外用 JSDoc的原则，可以使代码既易读又便于维护和文档化。保持团队风格一致即可。