WebStorm 设置注释符后自动加空格

注释设置

// 与 /* */ 注释在文字前加一个空格

vue 模版注释位置

为什么要加这个空格

WebStorm 默认用 Cmd + /（Windows 是 Ctrl + /）生成的行注释是 //代码 这样紧贴着的。这个默认值会带来两个实际麻烦。

第一是和 Prettier 打架。Prettier 格式化时会把 //代码 补成 // 代码，所以你按快捷键注释一行、保存时 Prettier 又改一次，git diff 里就多出一处无意义的改动。项目里一半人开了保存时格式化、一半人没开，这类噪音 diff 就会反复出现。

第二是 ESLint 的 spaced-comment 规则会直接报错。这条规则在很多流行的配置集里是默认开的（比如 eslint-config-standard），要求注释符后必须有空格：

// eslint 配置里对应这一条
{
  "rules": {
    "spaced-comment": ["error", "always"]
  }
}

把 IDE 的注释行为和 Prettier / ESLint 对齐，是消除这类摩擦最省事的办法——从源头就生成正确的格式，不用等工具来修。

设置的具体位置

正文第一张图那一处，完整路径是：

Settings → Editor → Code Style → 选具体语言（JavaScript / TypeScript / HTML 等）→ Code Generation 标签页

在 Comment Code 这一组下面有三个勾选项，含义分别是：

Line comment at first column — 行注释放在第一列。这个建议取消勾选。勾上的话在缩进很深的代码里注释会被顶到最左边，和代码的缩进层级完全脱节，读起来很难对应。取消后注释符跟着代码的缩进走。
Add a space at line comment start — 就是本文要开的这项，// 后自动加空格。
Block comment at first column — 块注释（/* */）放第一列，同样建议取消，理由和上面一样。
Add spaces around block comments — 块注释的 /* 和 */ 内侧加空格，生成 /* 代码 */ 而不是 /*代码*/。

要注意 Code Style 是按语言分别配置的，这是最容易漏的一点。在 JavaScript 下面改了，TypeScript、Vue、HTML、CSS、SCSS 各自还是默认值。如果项目里这几种文件都写，每个都得单独开一遍。快速确认哪些语言有这个选项：在 Settings 的搜索框里输 Add a space at line comment start，它会把所有包含这个选项的语言页面列出来。

Vue 文件的情况更特殊：SFC 里 <template> 段落走 HTML 的注释规则（生成 ），<script> 段落走 JS/TS 的规则，<style> 段落走 CSS 的规则。所以正文第二张图对应的是 HTML 那一处的配置，和 JS 那处是两回事。

让配置跟着项目走：EditorConfig

上面这些设置存在 IDE 的用户配置里，只对你自己的机器生效。团队协作时更好的做法是把风格约束写进项目，让所有人（甚至用不同编辑器的人）自动一致。

WebStorm 原生支持 EditorConfig，在项目根目录建 .editorconfig：

root = true

[*]
charset = utf-8
end_of_line = lf
insert_final_newline = true
trim_trailing_whitespace = true
indent_style = space
indent_size = 2

[*.md]
trim_trailing_whitespace = false

标准的 EditorConfig 属性里没有注释空格这一项，但 JetBrains 扩展了一批 IDE 专属属性，可以直接把 Code Style 的设置写进去：

[{*.js,*.jsx,*.ts,*.tsx}]
ij_javascript_line_comment_add_space = true
ij_javascript_line_comment_at_first_column = false
ij_javascript_block_comment_at_first_column = false

这些 ij_ 前缀的属性只有 JetBrains 系 IDE 认，其它编辑器会忽略掉，不会报错。想拿到完整的属性列表不用去查文档：在 Settings → Editor → Code Style 页面右上角的齿轮菜单里选 Export → EditorConfig File，它会把当前的全部 Code Style 设置导出成 .editorconfig 格式，你从里面挑需要的行复制出来就行。

.editorconfig 存在时，WebStorm 会优先用它、覆盖掉 Settings 里的对应设置。如果发现改了 Settings 没生效，先看项目里有没有 .editorconfig，多半是它在起作用。这个覆盖关系还可以在 Settings → Editor → Code Style 顶部的 Enable EditorConfig support 开关里关掉。

常用的注释快捷键

顺手记一下这几个，比手敲注释符快：

Cmd + / / Ctrl + / — 行注释，切换（已注释的会取消注释）。多行选中后逐行加。
Cmd + Option + / / Ctrl + Shift + / — 块注释。选中一段代码后用它包起来，适合注释掉一整块。
在 JS 函数上方输入 /** 然后回车 — 自动生成 JSDoc 骨架，参数列表会根据函数签名自动填好：

/**
 * @param {string} name
 * @param {number} age
 * @return {string}
 */
function greet(name, age) {
  return `${name} is ${age}`;
}

这个自动生成的行为由 Settings → Editor → General → Smart Keys 下的 Insert documentation comment stub 控制，默认是开的。