atom注释功能依赖语法识别（grammar），右下角language mode必须匹配代码类型，否则ctrl+/等快捷键无效；块注释需手动绑定editor:toggle-block-comment；docblockr仅在声明行且scope正确时生效；文件头注释需atom-file-header插件并手动配置。
Atom 本身支持快捷注释，但「快」不取决于键位熟不熟，而在于当前文件是否被正确识别为对应语言——按 Ctrl+/（Windows/Linux）或 Cmd+/（macOS）没反应，90% 是 grammar 没对。
确认右下角 language mode 是否匹配代码类型
注释逻辑由 grammar（语法包）驱动，不是编辑器硬编码的。如果右下角显示 Plain text，Ctrl+/ 就只会插入普通字符，不会加 // 或 #。
- 点一下右下角那个标签 → 手动选
JavaScript (Babel)（比纯JavaScript支持更多 ESNext 语法）、Python、PHP等真实语言项 - 临时验证：按
Ctrl+Shift+P（Win/Linux）或Cmd+Shift+P（macOS），输入Grammar: Show Grammar，看输出是不是类似source.js或source.python -
.vue文件的<script></script>块默认是text.html.vue，得进 Settings → Packages → DocBlockr → Language Specific Settings，把text.html.vue映射到source.js
区分行注释和块注释的触发方式
Ctrl+/ 默认调用的是 editor:toggle-line-comments，它只处理单行/多行首部注释；想用 /* */ 包裹式块注释，必须手动绑定 editor:toggle-block-comment。
- 单行光标：加/删
//（JS）、#（Python）等行注释符 - 多行选中：对每行分别加/删行注释，不是包裹成一块
- 块注释需额外配置：打开
keymap.cson，加入类似下面这段（注意 scope 必须匹配当前 grammar）：'.source.js, .source.jsx': 'ctrl-alt-/': 'editor:toggle-block-comment'
- 别用泛用选择器如
*，否则可能在设置页或终端里误触发
DocBlockr 插件生成函数注释的硬性条件
不是输 /** + Tab 就能出注释，它只在两个条件同时满足时才工作：光标必须落在函数/变量声明行上，且该文件 grammar 必须是它支持的 scope（如 source.js）。
- 光标位置要准：必须在
function foo()、const bar = () => {}或class Baz {这整行的任意位置，不能在空行、函数体内部或注释里 - 箭头函数仅支持声明式写法（
const fn = (a, b) => {}），匿名内联（arr.map(x => x * 2)）不识别 - 解构参数（
({ a, b })）或 TypeScript 类型（(a: string)）会导致参数名提取失败，此时直接手敲@param再按 Tab，DocBlockr 会补全后续字段 - Vue 单文件组件中，
<script></script>块需先手动切换 grammar 到source.js或source.ts，否则静默失效
头部作者/时间注释必须靠插件，且变量只首次求值
Atom 原生不支持新建文件自动插入 ${author} 或 ${date}，必须装 atom-file-header 并手动填三项配置。
- Author Name 必须在插件设置页里手动输入，它不读 Git 的
user.name，留空就真为空 - Template 必须顶格写（尤其 Python 模板，第一列就得是
#），缩进错位会导致注释不生效 -
${date}和${datetime}格式由 Date Format 控制，填YYYY-MM-DD HH:mm:ss才出 2026-10-09 22:44:00，小写yyyy会原样输出字面量 - 变量只在首次执行
Ctrl+Alt+I（Win/Linux）或Cmd+Alt+I（macOS）时求值，保存不会刷新时间——想更新就得再按一次
真正容易被忽略的是：所有注释行为都依赖 grammar scope，而 scope 错误时往往没有报错提示，只是“没反应”。与其反复试快捷键，不如先低头看一眼右下角。
