拒绝通知

此 PEP 已被拒绝。尽管社区可能对此感兴趣，但没有意愿使标准库遵循此标准。

摘要

此信息性 PEP 旨在为一致使用codetags提供指导，这将有助于构建标准实用程序来利用 codetag 信息，并使 Python 代码在不同项目之间更加统一。Codetags 还代表了一种非常轻量级的编程微范式，对于项目管理、文档、变更跟踪和项目健康监控非常有用。将其提交为 PEP 是因为它的一些想法被认为是 Pythonic 的，尽管这些概念并非 Python 编程所独有。本文档定义了 codetags、它们背后的理念、对标准化约定的动机、一些示例、一个规范、一个工具集描述以及对 Codetag 项目/范式可能的反对意见。

此 PEP 也作为一个 wiki 存在，供人们添加评论。

什么是 Codetags？

程序员广泛使用临时的代码注释标记约定，作为提醒需要更仔细检查或审查的代码段。标记的示例包括 FIXME、TODO、XXX、BUG，但现有软件中还有许多其他广泛使用的标记。此类标记将以后的提及为codetags。这些 codetags 可能出现在应用程序代码、单元测试、脚本、通用文档或任何合适的地方。

Codetags 已经在许多地方（例如 c2）被讨论和使用（Python 2.4 源代码中包含数百个 codetags）多年。有关更多历史和当前信息，请参阅 参考文献。

理念

如果您认同其中大多数价值观，那么 codetags 很可能对您有用。

1. 应将尽可能多的信息放在源代码中（应用程序代码或单元测试）。这与使用 codetags 一起可以防止重复。大多数文档都可以从该源代码生成；例如，通过使用 help2man、man2html、docutils、epydoc/pydoc、ctdoc 等。
2. 信息应几乎从不重复——应以单一的原始格式记录，所有其他位置应自动从原始位置生成，或仅被引用。这通常被称为单一真相来源（SPOT）或不要重复自己（DRY）规则。
3. 进入客户手中的文档应自动生成从单一来源到所有其他输出格式。人们希望以多种形式获得文档。因此，拥有一个能够生成所有这些文档的文档系统很重要。
4. 开发人员就是文档团队。他们编写代码，并且应该最了解代码。对于任何非大型项目，不应有专门的、独立的文档团队。
5. 纯文本（带有非侵入性标记）是编写任何内容的最佳格式。所有其他格式都应从纯文本生成。

Codetag 的设计受到了以下目标的影响

1. 注释应尽可能简短。
2. Codetag 字段应该是可选的，并且长度最小。默认值和自定义字段可以由各个代码商店设置。
3. Codetags 应极简。 jot 下某事的速度越快，jot 下的可能性就越大。
4. codetags 最常见的用法只有零到两个字段，这些字段应该最容易键入和阅读。

动机

• 围绕 codetags 可以构建各种生产力工具。

  请参阅 工具。

• 鼓励一致性。

  历史上，这些 codetags 的一个子集已在大多数现有源代码（无论是 Python 还是其他语言）中非正式使用。标签的使用方式不一致，拼写、语义、格式和位置各不相同。例如，一些程序员可能包含日期戳和/或用户标识符，限制为单行或不限制，codetag 的拼写方式与其他程序员不同，等等。

• 鼓励遵守 SPOT/DRY 原则。

  例如，动态地从 codetags 生成路线图，而不是让 TODO 与单独的路线图文档保持同步。

• 易于记忆。

  所有 codetags 都必须简洁、直观，并且在语义上与其他 codetags 不重叠。格式也必须简单。

• 使用不是强制/必需的。

  如果您还不使用 codetags，则没有义务开始使用，也没有影响代码的风险（但请参阅 反对意见）。可以采用一小部分 codetags，并且 工具 仍然有用（可能已经在临时的基础上采用了几个 codetags）。此外，识别和删除（以及可能记录）不再被认为有用的 codetag 非常容易。

• 提供代码的全局视图。

  可以使用工具生成文档和报告。

• 捕获 CRC/故事/需求的一个逻辑位置。

  XP 社区通常不以电子方式捕获故事，但 codetags 似乎是查找它们的一个好地方。

• 极度轻量级的流程。

  为每一个想法创建跟踪系统中的票证会降低开发速度。即使采用了票证系统，codetags 对于简单地包含指向这些票证的链接也很有用。

示例

这显示了一个简单的 codetag，正如在各种源代码中常见的（添加了一个尾随的 <>）

# FIXME: Seems like this loop should be finite. <>
while True: ...

以下人为的例子演示了 codetags 的典型用法。它使用了一些可用字段来指定分配者（一对程序员，首字母缩写为MDE和CLE）、预期完成日期（第 14 周）以及项目的优先级（2）

# FIXME: Seems like this loop should be finite. <MDE,CLE d:14w p:2>
while True: ...

此 codetag 显示了一个 bug，其中包含描述作者、发现（起源）日期、到期日期和优先级的字段

# BUG: Crashes if run on Sundays.
# <MDE 2005-09-04 d:14w p:2>
if day == 'Sunday': ...

以下是演示如何不使用 codetags 的方法。这有很多问题：1）Codetags 不能与代码共享一行；2）助记符后缺少冒号；3）引用 codetags 的 codetag 通常是无用的，而且更糟糕的是，它无法完成；4）对于一个微不足道的 codetag，不需要有一堆字段；5）不应使用具有未知值的字段（t:XXX）

i = i + 1   # TODO Add some more codetags.
# <JRNewbie 2005-04-03 d:2005-09-03 t:XXX d:14w p:0 s:inprogress>

规范

这描述了格式：语法、助记符名称、字段和语义，以及单独的 DONE 文件。

# MNEMONIC: Some (maybe multi-line) commentary. <field field ...>

# TODO: Recurse into subdirs only on blue
# moons. <MDE 2003-09-26>
[2005-09-26 Oops, I underestimated this one a bit.  Should have
used Warsaw's First Law!]

# FIXME: ...
...

工具

当前，程序员（有时还有分析师）通常使用grep来生成对应于单个 codetag 的项目列表。然而，各种假设的生产力工具可以利用一致的 codetag 格式。以下是一些示例工具。

文档生成器

可能的文档：词汇表、路线图、man pages

Codetag 历史记录

跟踪（通过修订控制系统接口）代码段中 BUG 标签（或任何 codetag）的起源/解决时间

代码统计

项目健康指示器

Codetag Lint

通知 codetags 的无效使用，并协助迁移到 codetags

故事管理器/浏览器

一种电子方式来替代 XP 便签卡。在 MVC 术语中，codetag 是模型，故事管理器可以是图形化查看器/控制器，用于进行可视化重排、优先级排序和分配、里程碑管理。

任何文本编辑器

用于更改、删除、添加、重新排列、记录 codetags。

已经存在一些工具利用了一组较小的伪 codetags（请参阅 参考文献）。还有一个正在进行的 codetags 实现示例，称为 Codetag Project。

反对意见

反对意见：

极限编程认为不应在代码中存在此类 codetags，因为代码就是文档。

辩护：

也许您应该将 codetags 放在单元测试文件中。此外，从未注释的代码生成文档非常困难。

反对意见：

现有的代码太多未遵循建议的准则。

辩护：

[简单] 实用工具（ctlint）可以转换现有代码。

反对意见：

导致与跟踪系统重复。

辩护：

并非如此，除非字段被滥用。如果一个项目存在于跟踪器中，codetag 的跟踪器字段中的简单票证编号就足够了。也许重复的标题是可以接受的。此外，为开发者随想随想的每一项都创建一个票证太麻烦了。此外，对于适合将相关数据放入 codetag 的简单或小型项目，跟踪系统可能会被淘汰。

反对意见：

Codetags 很难看，并且会弄乱代码。

辩护：

这是一个很好的观点。但我仍然宁愿将此类信息放在一个地方（源代码）而不是各种其他文档中，这些文档可能会重复或被遗忘。已完成的 codetags 可以发送到 DONE 文件，或发送到垃圾桶。

反对意见：

Codetags（以及所有注释）都会过时。

辩护：

如果其他来源（外部可见文档）依赖于它们的准确性，则不会有太多过时。

反对意见：

Codetags 很少有任何形式的估计完成日期。好的，字段是可选的，但您想建议那些确实会被广泛使用的字段。

辩护：

如果一个项目无法估算，则不要费心指定日期字段。使用工具按到期日期和/或优先级对项目进行排序和/或着色，更容易进行估算。让您的路线图成为 codetags 的动态反映，会使您更有可能保持 codetags 的准确性。

反对意见：

应在 <> 中使用字段参数的命名变量，而不是使用隐晦的单字符前缀。即，<MDE p:3> 应该写成 <author=MDE, priority=3>。

辩护：

拼写出字段的输入/冗余太多。我认为 p:3 i:2 与 priority=3, iteration=2 一样易读，并且更有可能被输入和记住（参见 理念 中的项目 C）。在这种情况下，实用性胜过纯粹性。需要跟踪的字段不多，因此单字母前缀是合适的。

反对意见：

应弃用同义词，因为最好只有一种拼写方式。

辩护：

许多程序员偏爱简短的助记符，尤其是在注释中。这就是选择简短助记符作为主要名称的原因。然而，其他人认为明确的拼写不易引起混淆且不易出错。关于这个问题，总会有两个阵营。因此，应继续支持同义词（以及完整的拼写）。

反对意见：

使用（对于助记符）不透明的缩写和省略元音的缩写是很残酷的，很难弄清楚这些东西。基于这一点，我讨厌：MLSTN RFCTR RFE FEETCH, NYI, FR, FTRQ, FTR WKRD RVDBY

辩护：

助记符是首选，因为它们很容易记住，并且占用的空间更少。如果程序员不喜欢省略元音，我们就无法在一行中容纳太多代码。对于那些写单行注释的人来说，空间很重要。但是，当随处使用同一个助记符时，将某项内容放在一行上的可能性就大大降低了。

反对意见：

输入字段花费太长时间。

辩护：

那么不要使用（其中大部分或全部）它们，特别是如果你是唯一的程序员。用 <> 终止 codetag 是件小事，通过这样做，您就可以使用建议的工具。编辑器对 codetags 的自动完成也很有用：您可以对编辑器进行编程，使其仅用一两个按键就能生成一个模板（例如 # FIXME . <MDE {date}>）。

反对意见：

工作周是一个模糊且不常见的计时单位。

辩护：

这是真的，但它是一个高度适合用于估算/定位目的的粒度单位，并且非常紧凑。 ISO 8601 被广泛理解，但它只允许您指定一个特定的日期（限制性）或月份（广泛性）。

反对意见：

我从美学上不喜欢在字段为空的情况下用 <> 结束注释。

辩护：

有必要有一个终止符，因为 codetags 可能后面跟着非 codetag 的注释。或者 codetags 可以限制为单行，但这会产生限制。我想不出任何恰当且明显优于 <> 的单字符终止符。也许 @ 可以作为终止符，但那样大多数 codetags 都会有一个不必要的 @。

反对意见：

我无法在编写 HTML 或更具体地说 XML 时使用 codetags。也许 @fields@ 会比 <fields> 作为分隔符更好。

辩护：

也许你是对的，但 <> 在适用时看起来更美观。XML/SGML 可以使用 @，而更常见的编程语言则坚持使用 <>。

参考资料

一些其他工具也尝试定义/利用 codetags。请参阅 http://tracos.org/codetag/wiki/Links。