Coding Style（一）——常见代码注释标签

文章摘要

GPT 4o

所有的代码规范、接口设计以及各种规定，都是为了在团队内部形成共识，防止个人习惯差异引起的混乱。

你可能会在代码注释中见过以下的内容：

# TODO: implement the algorithm here
...
# FIXME: late at night, I need some sleep

使用这些注释标签可以很方便地搜索到代码可以被改进的地方，大多数 IDE 都会有一个专门的视图来呈现这些内容。Python 中也有 PEP 350 介绍这些 Codetags，尽管这个 PEP 被拒了，但还是有非常多有意思的点。

常见的注释标签

我根据对代码的影响程度大小将不同的注释标签分为了蓝色组、橙色组、红色组，影响程度依次加深。

蓝色组表示代码可以运行，但是需要更多的功能或更多的解释。

注释标签	用途	标签注释	PEP 350 解释
TODO	功能待实现	知道要实现什么功能，但还没开始写。	Informal tasks/features that are pending completion.
NOTE	代码实现描述	描述代码的工作原理等	Sections where a code reviewer found something that needs discussion or further investigation.

橙色组表示代码可以运行，但是不正确。

注释标签	用途	标签注释	PEP 350 解释
HACK	代码待优化	使用非正规的方法实现了功能，不应该进入生产环境。	Hacks: Temporary code to force inflexible functionality, or simply a test change, or workaround a known problem.
FIXME	代码需修复	有问题或者不能运行的代码，需要修正。	Areas of problematic or ugly code needing refactoring or cleanup.
BUG	代码有漏洞	有个 BUG。	Reported defects tracked in bug database.
REVIEW	代码待评审	代码可能是正确的，但是需要评审一下。
XXX	代码待优化	虽然能用但是丑陋的代码，未来有空需要优化，需要更好的抽象性、可维护性以及性能等。	Areas of problematic or ugly code needing refactoring or cleanup.