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

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

# 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.

# 红色组

红色组表示代码根本无法运行。

注释标签用途标签注释
ERROR代码抛异常代码出现了具体的、重复的错误,即可复现的异常。
BROKEN代码坏了代码坏了
更新于 阅读次数

请我喝[茶]~( ̄▽ ̄)~*

VXenomac 微信支付

微信支付

VXenomac 支付宝

支付宝