JSDoc泛型中何时应使用点符号？

嘿，这个问题问到点子上了——我日常看代码时也常碰到这两种JSDoc泛型写法的纠结，今天就把来龙去脉说清楚！

点符号的来历和作用 #

带点的Array.<Bar>是早期JSDoc和Closure Compiler采用的旧版泛型语法，那个点的作用就是明确分隔“容器类型（比如Array）”和它的“泛型参数（比如Bar）”，本质上是当时约定俗成的一种写法，用来表示“这是一个存放Bar类型元素的数组”。

哪种写法才是正确的？ #

直接给结论：不带点的Array<Bar>是当前标准、推荐的写法。

为啥这么说？因为后来JSDoc跟进了ECMAScript的泛型语法规范，和TypeScript里的泛型写法完全对齐了——这种写法更直观，符合现代JavaScript开发者的认知，而且现在主流工具（比如VS Code的智能提示、最新版JSDoc、ESLint的JSDoc插件）都完美支持，甚至有些工具会把带点的写法标记为过时语法。

当然也有例外：如果你的项目还在使用非常老旧的JSDoc版本（比如JSDoc 3.5之前），或者必须适配Closure Compiler的传统语法规则，那带点的写法可能还能生效，但这种场景现在已经越来越少见了。

何时用/不用点符号？ #

• 优先用不带点的写法：绝大多数现代项目里，直接写Array<Bar>、Map<string, number>这种和TS一致的写法就好，工具兼容性拉满，可读性也更强。
• 只有必要时用带点的写法：如果项目必须兼容老旧的解析工具，或者代码要适配特定的旧版编译规则，才暂时用Array.<Bar>这种写法，但建议尽量升级工具，过渡到新标准。

举个直观的对比例子：

// 推荐的现代写法
/**
 * @param {Array<Bar>} bars 需要被处理的bars数组
 */
function foo(bars) {}

// 旧版兼容写法（仅在必要时使用）
/**
 * @param {Array.<Bar>} bars 需要被处理的bars数组
 */
function foo(bars) {}

内容的提问来源于stack exchange，提问作者Konrad Höffner