前言

很多人都知道，代码中待办的事项会用TODO注释，标记还未完成的待办项。但事实上，很多项目中TODO已经烂大街了。我们后端项目中，仅仅游戏业务代码中就存在近百处TODO（上线之前曾经治过，只是又复发了），并且还在持续增加中。长此以往下去，TODO已经和常规注释没有差别了。

TODO的初衷

1

// TODO + 说明：如果代码中有该注释，说明在该注释处有功能代码待编写，待实现的功能在说明中会简略说明。

如何有效使用TODO

我们都知道TODO是一个特殊注释，用以区分常规注释，并且在编辑器中会高亮显示。

我相信下图代码的作者，开始写代码的时候，确实还没想好具体协议相关的操作要怎么实现，所以临时写了一个TODO以防忘记。但在具体实现了代码之后，却忘记删除TODO注释了。

TODO1

而且这样的TODO太多了之后，整个项目中已经不知道哪些TODO已经完成，哪些TODO还需要实现，这对项目管理是极为不利的。

对于游戏项目，版本节奏很快，更新频率很高，对于TODO的管理，更需要主程操心，每个版本结版本之前必须检查一下，是否有影响到版本质量的TODO还未清理，是否存在已经完成的TODO依然存在着。

其他特殊注释

1
2
3
4

// FIXME + 说明：如果代码中有该注释，说明该注释处代码需要修正，甚至代码是错误的，不能工作，需要修复，如何修正会在说明中简略说明。


// XXX + 说明：如果代码中有该注释，说明注释处代码虽然实现了功能，但是实现的方法有待商榷，希望将来能改进，要改进的地方会在说明中简略说明。

简单来说，FIXME用来标识待修复项，XXX用来标识待优化项。当然每个版本结版本之前检查一下还是很重要的，否则这些注释就失去了原来的意义了。

代码规范（特殊注释）

  • 当前版本内必须要做的待办事项使用TODO注释，并在完成后删除注释；
  • 非当前版本内的待办项，或非紧急的优化内容，可使用XXX注释，并标明时限；
  • bug修正理论上应该及时修复，如实际情况存在放到下个版本修复的bug，使用FIXME注释，并标明修复时限或版本号；
  • 主程应该每个版本检查TODO注释是否及时清零，并对FIXME和XXX的时效性进行检查并及时清理；
1
2
3
4
5
6
7

// 特殊注释

// TODO 后续补充发送邮件逻辑--1.1.0

// XXX 此模块因版本节奏太紧，存在优化空间，计划1.2.0版本进行优化

// FIXME 此逻辑在极低概率下会出现显示错误的情况，与策划讨论后计划下个优化版本再修复(2020/08/20)

微信公众号