项目代码开发过程当中,
不论是读者去读别人的代码,
还是作为开发者去编写一段代码,
会遇到一些特殊的场合(因素),
使的开发当事人不得不暂时跳过这个逻辑(事已至此,生活仍需继续下去)。
但作为一个负责任的设计者或者维护者,需要通过注释线索,提醒给后面维护维护人员。
但这种实用性的需求,不论下至谭浩强,上至软件工程,乃至 Agile 也没有明确告诉开发者如何处理。
但是程序猿的世界总是有它自身的发展规律,通过学习前辈们的留下来的经验,代码编写有一些浪漫的约定规则,这些特殊的约定规则,帮助开发者还是读者传递一些代码线索,这些线索会穿越时空,起承转合,让前人后人之间心领神会。
最为常见的注释标记有以下三个TODO、FIXME、XXX
不少 IDE 对注释中这三个关键字高亮显示。
TODO
从字面意思也很好理解,该关键字所表达的含义是待实现,目前尚未实现的功能。
e.g.
/// TODO frank 2022-05-27
/// this function MUST validate the parameter, but wait for interface A now.
FIXME
该关键字表达的含义是此处代码实现有问题,先临时实现,须要后续的修正。
e.g.
/// FIXME frank 2022-05-27
/// not robust enough in multi-thread,
/// most of the time running well,
/// i sugguest add thread-safe protection.
XXX
也是表示后续代码须要修正,更多强调的是对代码进行优化。
e.g.
/// XXX frank 2022-05-27
/// there is a prepositional condition here.
/// the sizeof(data) MUST be large enough for duplicated packet.
/// the maintainers MUST pay attention on it.