拒绝通知

该 PEP 已被拒绝。虽然社区可能感兴趣，但没有人希望让标准库符合此标准。

摘要

这份信息性 PEP 的目的是为一致使用代码标签提供指南，这将使构建标准实用程序成为可能，以利用代码标签信息，并使 Python 代码在不同项目中更加统一。 代码标签也代表了一种非常轻量级的编程微范式，在项目管理、文档、变更跟踪和项目健康状况监控方面变得有用。 这是作为 PEP 提交的，因为它的想法被认为是 Pythonic 的，尽管这些概念并非 Python 编程所独有。 这里定义了代码标签、它们背后的理念、标准化约定的动机、一些示例、规范、工具集描述以及对 Codetag 项目/范式的可能异议。

该 PEP 也是一个 wiki，供人们添加评论。

什么是代码标签？

程序员广泛使用临时代码注释标记约定，作为对需要仔细检查或审查的代码部分的提醒。 标记示例包括 FIXME、TODO、XXX、BUG，但在现有软件中还有更多广泛使用。 此类标记将从现在起被称为代码标签。 这些代码标签可能会出现在应用程序代码、单元测试、脚本、一般文档或任何合适的地方。

代码标签在许多地方（例如，c2）经过多年的讨论和使用（Python 2.4 源代码中有数百个代码标签）。 请参阅 参考文献，以获取更多历史和当前信息。

理念

如果您赞同大多数这些价值观，那么代码标签可能对您有用。

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

代码标签设计受到以下目标的影响

1. 评论应尽可能简短。
2. 代码标签字段应为可选且长度最短。 默认值和自定义字段可以由各个代码商店设置。
3. 代码标签应尽量简洁。 记录信息越快，记录的可能性就越大。
4. 代码标签最常见的用途只会指定零到两个字段，这些字段应该是最容易键入和阅读的。

动机

• 可以围绕代码标签构建各种生产力工具。

  请参阅 工具.

• 鼓励一致性。

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

• 鼓励遵守 SPOT/DRY 原则。

  例如，从代码标签动态生成路线图，而不是将 TODO 与单独的路线图文档保持同步。

• 易于记忆。

  所有代码标签都必须简洁、直观且在语义上不与其他代码标签重叠。 格式也必须简单。

• 无需/强制使用。

  如果您还没有使用代码标签，则没有义务开始，并且没有影响代码的风险（但请参阅 反对意见）。 可以采用一个小的子集，并且 工具 仍然有用（一些代码标签可能已经以临时方式被采用）。 此外，识别和删除（并可能记录）不再被认为有用的代码标签非常容易。

• 提供代码的全局视图。

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

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

  XP 社区通常不以电子方式捕获故事，但代码标签似乎是定位它们的好地方。

• 极其轻量级的流程。

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

示例

这显示了一个简单的代码标签，它通常在各个来源中找到（增加了尾随的 <>）

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

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

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

该代码标签显示了一个错误，其字段描述了作者、发现（起源）日期、截止日期和优先级

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

这是一个如何不使用代码标签的演示。 这有许多问题：1) 代码标签不能与代码共享一行； 2) 助记符后缺少冒号； 3) 引用代码标签的代码标签通常毫无用处，更糟糕的是，它无法完成； 4) 无需为一个微不足道的代码标签设置一堆字段； 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 来生成与单个代码标签对应的项目列表。但是，各种假设的生产力工具可以利用一致的代码标签格式。以下是一些示例工具。

文档生成器

可能的文档：词汇表、路线图、手册页

代码标签历史记录

跟踪（使用版本控制系统接口）何时在代码部分中生成/解决 BUG 标签（或任何代码标签）。

代码统计

项目健康度计

代码标签 Lint

通知代码标签使用不当，并帮助移植到代码标签。

故事管理者/浏览器

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

任何文本编辑器

用于更改、删除、添加、重新排列、记录代码标签。

已经存在一些工具，它们利用了更小的伪代码标签集（参见 参考资料）。还有一个正在进行的代码标签实现示例，称为 代码标签项目。

反对意见

异议：:

极限编程认为，代码中不应该存在这些代码标签，因为代码就是文档。

辩护：:

也许你应该将代码标签放在单元测试文件中。此外，从没有注释的源代码中生成文档很难。

异议：:

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

辩护：:

[简单] 实用程序 (ctlint) 可以转换现有的代码。

异议：:

导致与跟踪系统重复。

辩护：:

并非如此，除非滥用字段。如果跟踪系统中存在项目，则代码标签跟踪器字段中简单的工单号就足够了。也许重复的标题是可以接受的。此外，为开发人员在旅途中想到的每个项目都提交工单太麻烦了。此外，对于简单或小型项目，跟踪系统可能会被省略，这些项目可以将相关数据合理地放入代码标签中。

异议：:

代码标签很丑，会使代码混乱。

辩护：:

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

异议：:

代码标签（以及所有注释）会过时。

辩护：:

如果其他来源（外部可见文档）依赖于它们的准确性，则不会出现这种情况。

异议：:

代码标签往往很少有估计的完成日期。好吧，这些字段是可选的，但你想建议一些实际上会被广泛使用的字段。

辩护：:

如果一个项目不可估量，就不要费心指定日期字段。使用工具按截止日期和/或优先级对项目进行排序和/或颜色编码，更容易进行估计。让您的路线图动态地反映您的代码标签，这样您更有可能保持代码标签的准确性。

异议：:

应使用 <> 中字段参数的命名变量，而不是神秘的单字符前缀。即，<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

辩护：:

助记符是首选，因为它们很容易记住，占用空间更小。如果程序员不喜欢省略元音，那么我们在每一行上只能写很少的代码。对于那些经常写一行注释的程序员来说，空间很重要。但是，在所有地方都使用一个标准，就更不可能出现一行放不下这种情况了。

异议：:

输入字段需要花费太长时间。

辩护：:

那么就不要使用（大部分或全部）它们，尤其当你只是唯一一个程序员的时候。用 <> 结束代码标签是一件小事，这样做就能使用提议的工具。编辑器自动补全代码标签也很有用：你可以将你的编辑器设置为用一个或两个键来输入一个模板（例如，# FIXME . <MDE {date}>）。

异议：:

WorkWeek 是一个模糊且不常见的计时单位。

辩护：:

这是真的，但它是一个非常适合用于估计/目标的粒度单位，而且它非常紧凑。 ISO 8601 被广泛理解，但只允许你指定具体的一天（限制性）或月份（宽泛）。

异议：:

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

辩护：:

需要一个终止符，因为代码标签后面可能跟着非代码标签注释。或者代码标签可以限制在一行，但这很限制。我无法想到任何合适的、明显优于 <> 的单字符终止符。也许 @ 可以作为终止符，但这样大多数代码标签就会有一个不必要的 @。

异议：:

在编写 HTML 或更笼统地说，在编写 XML 时，我无法使用代码标签。也许 @fields@ 比 <fields> 更适合作为分隔符。

辩护：:

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

参考文献

一些其他工具也尝试过定义/利用代码标签。参见 http://tracos.org/codetag/wiki/Links。