工作区工具

代码中的 TODO

TODO 是某个人对自己许下、随即弄丢的承诺。它写在问题所在之处,也就是再也没人回头看 的地方;等到它真正要紧的时候,写下它的人早已换了团队。grep 能找到它们,而一千行 grep 输出等于没找到。

分析器面板的 TODO 标签页会把它们全部读出来,然后做 grep 做不到的事:分组。从状态 栏或命令面板(代码中的 TODO)打开面板,切到第二个标签页。

状态栏会把标记数量显示在分析器的错误与警告旁边;点击那个计数即可打开本标签页。

按负责人分组的 TODO 标签页

什么算一条标记

Git 已跟踪、或将会跟踪的文件里,注释中的一个标签:

写法 读作
// TODO: 把它发出去 标签 TODO,无负责人
//todo 把它发出去 同上——冒号和空格都可省略
# todo 把它发出去 同上——大小写和语言都不影响
/* TODO(cgm): 把它发出去 */ 标签 TODO,负责人 cgm
-- TODO (CGM) 把它发出去 同一个负责人:cgm、(CGM)、[cgm] 是一个人
<!-- TODO: @cgm 把它发出去 --> 还是同一回事

标签有 TODO、FIXME、BUG、HACK、XXX、NOTE、OPTIMIZE、REVIEW、 REFACTOR、DEPRECATED、QUESTION、IDEA、WIP 和 TEMP。前四个带颜色,因为 “这里坏了”和“这是我的一个想法”不该在同一份列表里长得一样。

标签必须跟在注释起始符后面——//、#、--、;、%、/*、*、<!--、"""。 除此之外都不算:todo = [l for l in lines] 是代码,而把一次变量赋值记成债务的面板, 不会有人信第二次。同一条规则也把叫 reviewNotes 的函数挡在列表之外。

分组才是重点

四个维度,各一次点击:

分组方式 回答的问题
标签 这个仓库背着哪一类债?
负责人 每个人留下了什么——以及无人认领的那一堆里有什么?
文件夹 目录树的哪个角落正在腐烂?
文件 当你已经知道要去哪里时的普通列表。

无人认领 是一个真正的分组,不是剩下的边角料:没人署名的标记正是永远没人接手的 标记,把它们数出来本身就是意义所在。

顶部的标签胶囊会筛选列表;点击行内的负责人徽章同样如此,搜索框则会匹配内容、文件、 标签和负责人。仅已更改 会收窄到你改过但尚未提交的文件——推送前的最后一道检查, 此刻一小时前留下的 // FIXME 即将变成永久的。

点击一行会在对应行号打开文件。

它不做的事

  • 只读,从不写。 没有“标记为完成”:关掉一个 TODO 的办法是删掉那一行并提交。若想 要一份 Gitcito 替你保管的清单,见 待办——那是完全不同的东西:住在应用 里、而不是源码里的私人笔记。
  • 忽略的文件会被跳过,node_modules 也一样,无论里面的标签写了什么。未跟踪的 文件则会包含在内:五分钟前写下的标记,最值得看见。
  • 它分不清注释和字符串。 对扫描来说,const banner = "// TODO" 这一行就是一条 标记。它没有四十种语言的解析器,也不假装有。
  • 扫描是一张快照。 编辑文件后,面板会保留原来的数字,直到你再扫一次;刷新按钮就 是全部故事。
  • 它在 5000 条处停下。 超过这个数的仓库,其债务问题不是一块面板能解决的。

它在哪里运行

对工作区执行一次 git grep,这正是它只用毫秒、而问题标签页要用几秒的 原因:不编译任何东西,不牵动任何工具链,并且跳过二进制文件和被忽略的路径——因为 Git 早就知道那些是哪些。

在 GitHub 上改进这份翻译