PEP 350：标准码

每个代码标签应该在注释中，并且可以是任意数量的 行。它不应与代码共享一行。它应与周围代码的 缩进相匹配。代码标签的末尾标有 一对尖括号``<>``包含可选字段，必须 不能分成多行。最好在``＃``注释中使用代码标签 而不是字符串注释。每个代码标签可以有多个 字段，所有这些字段都是可选的。 ...注意：允许字段适合多个字段可能是合理的 行，但是如果你使用这么多字段，它会使解析和失败极简主义变得复杂。 简而言之，代码标签由一个助记符，冒号，评论文本， 一个开放角括号，一个可选的字段列表，以及一个结束 角括号。例如，:: #MNEMONIC：一些（可能是多行）评论。 < field field ...> 助记符 --------- 的代码标签兴趣如下所示，使用以下格式： | ``推荐助记符（&同义词列表）`` | *规范名称*：语义 ``TODO（MILESTONE，MLSTN，DONE，YAGNI，TBD，TOBEDONE）`` *待办事项*：非正式待完成的任务/功能。 ``FIXME（XXX，DEBUG，BROKEN，REFACTOR，REFACT，RFCTR，OOPS，SMELL，NEEDSWORK，INSPECT）`` *修复我*：需要重构的问题或丑陋代码区域或 清理。 ``BUG（BUGFIX）`` *错误*：在bug数据库中跟踪报告的缺陷。 ``NOBUG（NOFIX，WONTFIX，DONTFIX，NEVERFIX，UNFIXABLE，CANTFIX）`` *不会被修复*：由于设计问题或域名限制而众所周知但永远无法解决的问题。 ``REQ（要求，故事）`` *要求*：满足特定的正式要求。 ``RFE（FEETCH，NYI， FR，FTRQ，FTR）`` *要求增强*：路线图项目尚未实施。 ``IDEA`` *想法s *：可能的RFE候选人，但不如RFE正式。 `` ??? （QUESTION，QUEST，QSTN，WTF）`` *问题*：误解了细节。 `` !!! （ALERT）`` *提醒*：需要立即关注。 ``HACK（CLEVER，MAGIC）`` * Hacks *：临时代码强制使用不灵活的功能，或者只需更改测试，或者解决已知问题。 ``PORT（可移植性，WKRD）`` *可移植性*：特定于操作系统，Python版本等的变通方法。 ``CAVEAT（CAV，CAVT，警告，注意）`` *警告*：实现细节/陷阱，因为 不直观。 ``注意（帮助）`` *注意*：代码审查员发现需要讨论或进一步调查的事项。 ``常见问题解答'` *常见问题*：有趣的区域需要 外部解释。 ` GLOSS（术语表）`` *词汇表*：项目词汇表的定义。 ``查（REF，REFERENCE）`` *参见*：指向其他代码的指针，web lin k等。 ``TODOC（DOCDO，DODOC，NEEDSDOC，EXPLAIN，DOCUMENT）`` *需要文档*：仍然代码区域需要 记录。 ``CRED（CREDIT，谢谢）`` *积分*：外部认证提供启示。 ``STAT（STATUS）`` *状态*：文件级统计指标的成熟度这个 文件。 ``RVD（审查，审查）`` *已审核*：审核已进行的文件级指标。 /> 文件级代码标签可能更适合作为 版本控制系统中的属性，但仍可在 a codetag中适当指定。 其中一些是临时的（例如，``FIXME``），而其他的是持久的（例如，``REQ``）。使用三个标准选择了一个同义词 的助记符：描述性，长度（越短越好）， 常用。 选择``FIXME``和``XXX``是很困难的。 ``XXX``似乎更为常见，但更少描述性。此外，``XXX``是一段代码中有用的占位符，其值不明。 因此``FIXME``是首选拼写。 太阳说___``XXX`` 和``FIXME``略有不同，给'XXX``更高的严重性。 然而，几十年关于这个话题的混乱，以及太多不受Sun影响的数百万b $ b开发者，很容易正确地称他们为同义词。 他们是同义词。 __ http://java.sun.com/docs/codeconv/ht....doc9.html#395 ``DONE``总是完成的` `TODO``项目，但这可能应该通过修订控制系统和/或完成 记录机制来指示。（参见`DONE File` _）。 br /> 计算``NOTE``标签可能是一个有用的指标：高计数可能 表示设计（或其他）问题。但是当然大多数 代码标签都表示需要注意的代码区域。 一个``FAQ``可能更适合在wiki中记录 用户可以更轻松地查看和贡献。 字段 ------ 所有字段都是可选的。建议的标准字段在本节中描述了 。请注意，大写字段字符打算被替换为。 * Originator / Assignee *和* Origination Date / Week *字段是 最常见，通常不需要前缀。 ...注意：前缀后面的冒号是一个新的添加成为当指出代号时，需要。字段（没有 数字），例如cTiger;与用户名无法区分。 < MDE 2005-9-24> ...注意：此部分仅以受让人和到期人员开始周。它要求b $ b已经成长为很多领域。对于任何值得使用它的物品，最好使用跟踪系统，并且 不能复制代码标签（字段）中的所有内容。 < MDE> 这个冗长的字段列表可能会使人们（预期的 极简主义者）远离采用代码标签，但请记住这些 仅用于支持以下程序员：1）喜欢以完整的形式保留``BUG`` 或``RFE``代码标签，或2）正在使用codetags为 他们完整且唯一的跟踪系统。换句话说，很多这些字段很少会被使用。它们主要来自 行业惯例，示例来源包括`GCC Bugzilla`__和'Python'的SourceForge`__跟踪系统。 ...... ???：也许包内的代码标签（__init__.py文件）可能具有特殊的全局意义 。 < MDE> __ http：// gcc.gnu.org/bugzilla/ __ http://sourceforge.net/tracker/?group_id=5470 ``AAA [，BBB] ...`` *发起人*或*受让人*首字母的名单（上下文 决定除非两者都存在）。 也可以使用诸如``MicahE``之类的用户名而不是首字母。缩写 （大写）是首选形式。 ``a：AAA [，BBB] ......`` *受让人*首字母的清单。这仅在（罕见）情况下是必要的，其中代码标签同时具有受让人和发起人，并且 他们是不同的。否则省略``a：``前缀，并且 上下文确定意图。例如，``FIXME``通常有一个 *受让人*，而``NOTE``通常有一个* Originator *，但是如果一个 ``FIXME` `是由评论者发起的（和草签），然后 受让人的首字母需要一个``a：``前缀。 ` `YYYY [-MM [-DD]]``或``WW [.D] w`` *起始日期*表示添加评论的时间，在 `ISO 8601`_格式（仅限数字和连字符）。或者*起源 周*，用于指定*起始日期*的替代形式。 可以选择指定一周中的某一天。 w``后缀 是区分日期所必需的。 ``d：YYYY [-MM [-DD]]``或者``d：WW [.D] w`` *到期日（d）*目标完成（估计）。或*到期周（d）*， 指定*截止日期*的替代方案。 ``p：N`` *优先级（p）*级别。范围（N）从0..3开始，其中3是 最高。 0..3类似于低，中，高和 showstopper / critical。 * Severity *字段可以计算在 这个单个数字中，建议这样做，因为两个 都有不同的解释。范围和订单应该是可定制的。这个字段的存在对于逐项列出代码标记的任何 工具很重要。因此，应该支持（可自定义的）默认值 。 ``t：NNNN`` *跟踪器（t ）*与对应的票证ID相对应的号码在 单独的跟踪系统中。 以下字段也可用但预计会减少 普通。 ``c：AAAA`` *类别（c）*表示受此影响的特定区域 项目。 ``s：AAAA`` *状态*表示项目状态。示例是未探索的，b $ b理解，inprogress，固定，完成，关闭。注意 当项目完成时，最好删除 代码标签并将其记录在`DONE File`_中。 ``i：N`` 开发周期*迭代（i）*。用于将代码标记分组为 完成目标组。 ``r：N`` 开发周期*发布（r ）*。用于将代码标记分组为 完成目标组。 ..注意：SourceForge无法识别严重性，我认为 *优先*（以及单独的RFE代码标签）应该 包含和避免*严重性*。 < MDE> ..注意：这些工具需要能够按顺序对代码标记进行排序 的目标完成情况。我觉得* Priority *应该是 唯一，该可寻址顺序的唯一指标。其他 类别如*严重性*，*客户重要性*等等与商业逻辑相关的并且不应被 $ b $识别b代码标签工具。如果某些团体希望拥有这样的逻辑，那么它将b $ b最好地（外部）分解为单个值（优先级） 可以确定可操作项目的排序。 < MDE> 总结一下，非前缀字段是首字母和起源 日期，前缀字段是：受让人（a），到期（d），优先级 （p），跟踪器（t），类别（c），状态，迭代（i）和释放 （r） 。 组应该可以定义或添加自己的字段， 这些应该有大写前缀来区分它们与 标准集。自定义字段的示例是*操作系统（O）*， *严重性（S）*，*受影响的版本（A）*，*客户（C）*等 DONE文件 --------- 有些代码标签可以*完成*（例如，``FIXME ``， ``TODO``，``BUG``）。通过记录完成日期标记来保留已完成的项目 通常很重要。这些已完成的项目 最好存储在一个位置，全局到项目（或者可能是一个包）。建议的格式最容易通过一个例子描述， 说``〜/ src / fooproj / DONE`` :: ＃TODO：进入只在蓝色的子目录 ＃moons。 < MDE 2003-09-26> [2005-09-26哎呀，我有点低估了这个。应该用 使用华沙的第一定律！] ＃FIXME：... ... 您可以看到代码标签是从原始的 源文件中逐字复制的。然后在以下行输入日期戳 并附带可选的验尸评论。该条目以 空白行终止（``\ n \ n```）。 删除代码标签可能会很麻烦每次完成一个 的行。但实际上很容易设置一个Vim或 Emacs映射来自动记录这种格式的代码标签删除（没有评论）。 评论。 工具 ===== 目前，程序员（有时是分析师）通常使用* grep * 生成与单个代码标签对应的项目列表。 但是，各种假设的生产力工具可以利用 的一致代码标签格式。下面是一些示例工具。 ...注意：Codetag工具大部分未实现（但我已经开始了！/ b $ b）！< MDE> 文档生成器 可能的文档：词汇表，路线图，联机帮助页 代码标签历史 在代码部分发出/解决了``BUG``标签 （或任何代码标签）时跟踪（带修订控制系统界面） 代码统计 项目Health-O-Meter Codetag Lint 通知无效使用代码标签，并协助移植到codetags 故事管理器/浏览器 用于替换XP记录卡的电子方式。在MVC术语中， 代码标签是模型，故事管理器可以是图形化的 查看器/控制器，用于进行视觉重新排列，优先级排序和 任务，里程碑管理。 任何文本编辑器 用于更改，删除，添加，重新排列，录制 代码标签。 已经有一些工具可以利用 较小的伪代码标记集（参见参考文献_）。还有一个 示例代码标签实现，称为`Codetag Project`__。 __ http://tracos.org/codetag 异议 ========== ：异议：极限编程认为这样的代码标签不应该在代码中存在代码是文档。 ：防御：也许你应该把代码标签放在单元测试文件中 。此外，从 未注释的源代码生成文档很难。 ---- ：反对意见：太多现有代码未遵循建议 指南。 ：防御：[简单]实用程序（* ctlint *）可以转换现有代码。 ---- ：异议：导致跟踪系统重复。 ：防御：不是真的，除非字段被滥用。如果跟踪器中有一个项目，那么代码标签跟踪器字段中的简单票号就足够了。就足够了。也许一个重复的标题是可以接受的。 此外，为每个 项目提交的票证太过繁琐了。 -the去。此外， 跟踪系统可以用于简单或小型的b $ b项目，这些项目可以合理地将相关数据放入代码标签中。 ---- ：异议：代码标签是丑陋而杂乱的代码。 ：防御：这是一个好点。但是我还是宁愿在一个地方（源代码）比其他各种文件都有这样的信息 ， 可能会被复制或遗忘。完成的 代码标签可以发送到`DONE File`_，或者发送到 桶。 - --- ：异议：Codetags（和所有评论）都已过时。 ：防御：如果有其他来源，则不是那么多（外部可见 文档）取决于它们的准确性。 ---- ：异议：Codetags往往很少有估计完成 任何日期的日期。好的，这些字段是可选的，但你想 建议实际上会被广泛使用的字段。 ：防御：如果一个项目是无法估量的打扰指定 日期字段。使用工具显示订单和/或颜色的商品 到期日和/或优先级，更容易估算。 让您的路线图成为动态反映你的代码标签使得 你更有可能保持代码标准的准确性。 ---- ：异议：应该使用``<>` 中的字段参数的命名变量，而不是隐藏的单字符前缀。即， < MDE p：3>应该是< author = MDE，priority = 3> ;. ：防御：拼写/详细说明字段太多了。我认为``p：3 i：2``与``priority = 3， iteration = 2``一样可读，并且更有可能通过键入和记住 （参见Philosophy_中的子弹C）。在这种情况下，实用性胜过 纯度。跟踪的字段不多，所以一个字母 前缀是合适的。 ---- ：反对意见：同义词应该被弃用，因为最好有单一的方法拼写一些东西。 ：防御：许多程序员喜欢短暂的助记符名字，特别是 评论。这就是选择短助记符作为主要 名称的原因。然而，其他人认为明确的拼写不会让人感到困惑并且不容易出错。在这个问题上总会有两个阵营 。因此，同义词（和完整的，完整的拼写） 应该保持支持。 ---- ：异议：使用[助记符]不透明的首字母缩略词和 缩写使元音掉落是残忍的;很难想出这些东西 out。在此基础上我讨厌：MLSTN RFCTR RFE FEETCH，NYI，FR，FTRQ， FTR WKRD RVDBY ：防御：助记符是首选，因为它们很漂亮容易 记住并占用更少的空间。如果程序员不喜欢降低元音，我们可以在 行上输入非常少的代码。这个空间对于那些写评论的人来说非常重要，因为这些评论通常只适用于一行。但是当在任何地方使用佳能时， 不太可能让某些东西适合在线上。 ---- ：异议：键入字段需要很长时间。 ：防御：然后不要使用（大部分或任何）它们，特别是如果你'b 唯一的程序员。使用``<>``终止代码标签是一个很小的b / b $ b家务，这样你就可以使用建议的工具。 编辑器自动完成代码标签也很有用：你可以用编程你的编辑器来标记一个模板（例如``＃FIXME。< MDE {date}>``）只需一两次按键。 ---- ：异议：* WorkWeek *是一个不起眼的，不常见的时间单位。 /> ：防御：这是真的，但它是一个非常合适的粒度单位 用于估算/定位目的，它非常紧凑。 `ISO 8601`_被广泛理解，但允许您在特定日期（限制性）或月份（广泛）中仅指定 。 ---- ：反对：我在美学上不喜欢终止评论 with<>在空场的情况下。 ：防御：必须有一个终结器，因为代码标签可能是 ，然后是非代码标签注释。或者代码标签可以限制在一行中，但这是令人望而却步的。我不能想到任何 单字符终结符是合适的，并且比<>更好地比b $ b好​​。也许``@``可能是终结者，但是大多数 的代码标签都会有一个不必要的@。 ---- ：异议：在编写HTML时我不能使用代码标记，或者更少 特别是XML。也许`@ fields @``会比 ``< fields>``作为分隔符更好。 ：防御：也许你''是的，但是``<>``每当 适用时看起来更好。 XML / SGML可以使用``@``而更常见的 编程语言坚持``<>``。 参考资料 ========== 其他一些工具已经接近定义/利用代码标签。 参见http://tracos.org/codetag/wiki/Links. $b $b ... _wiki: http://tracos.org/codetag/wiki/Pep ... _ISO 8601: http: //en.wikipedia.org/wiki/ISO_8601 ... _c2: http://c2.com/cgi/wiki?FixmeComment ... Local Variables : mode: indented-text indent-tabs-mode: nil sentence-end-double-space: t fill-column: 70 End:Please read/comment/vote. This circulated as a pre-PEP proposalsubmitted to c.l.py on August 10, but has changed quite a bit sincethen. I''m reposting this since it is now "Open (under consideration)"at <http://www.python.org/peps/pep-0350.html>. Thanks! --Micah Elliott <mde at tracos.org>PEP: 350Title: CodetagsVersion: $Revision: 1.2 $Last-Modified: $Date: 2005/09/26 19:56:53 $Author: Micah Elliott <mde at tracos.org>Status: DraftType: InformationalContent-Type: text/x-rstCreated: 27-Jun-2005Post-History: 10-Aug-2005, 26-Sep-2005Abstract======== This informational PEP aims to provide guidelines for consistent useof *codetags*, which would enable the construction of standardutilities to take advantage of the codetag information, as well asmaking Python code more uniform across projects. Codetags alsorepresent a very lightweight programming micro-paradigm and becomeuseful for project management, documentation, change tracking, andproject health monitoring. This is submitted as a PEP because itsideas are thought to be Pythonic, although the concepts are not uniqueto Python programming. Herein are the definition of codetags, thephilosophy behind them, a motivation for standardized conventions,some examples, a specification, a toolset description, and possibleobjections to the Codetag project/paradigm. This PEP is also living as a wiki_ for people to add comments.What Are Codetags?================== Programmers widely use ad-hoc code comment markup conventions to serveas reminders of sections of code that need closer inspection orreview. Examples of markup include ``FIXME``, ``TODO``, ``XXX``,``BUG``, but there many more in wide use in existing software. Suchmarkup will henceforth be referred to as *codetags*. These codetagsmay show up in application code, unit tests, scripts, generaldocumentation, or wherever suitable. Codetags have been under discussion and in use (hundreds of codetagsin the Python 2.4 sources) in many places (e.g., c2_) for many years.See References_ for further historic and current information.Philosophy========== If you subscribe to most of these values, then codetags will likely beuseful for you. 1. As much information as possible should be contained **inside thesource code** (application code or unit tests). This along withuse of codetags impedes duplication. Most documentation can begenerated from that source code; e.g., by using help2man, man2html,docutils, epydoc/pydoc, ctdoc, etc. 2. Information should be almost **never duplicated** -- it should berecorded in a single original format and all other locations shouldbe automatically generated from the original, or simply bereferenced. This is famously known as the Single Point OfTruth (SPOT) or Don''t Repeat Yourself (DRY) rule. 3. Documentation that gets into customers'' hands should be**auto-generated** from single sources into all other outputformats. People want documentation in many forms. It is thusimportant to have a documentation system that can generate all ofthese. 4. The **developers are the documentation team**. They write the codeand should know the code the best. There should not be adedicated, disjoint documentation team for any non-huge project. 5. **Plain text** (with non-invasive markup) is the best format forwriting anything. All other formats are to be generated from theplain text. Codetag design was influenced by the following goals: A. Comments should be short whenever possible. B. Codetag fields should be optional and of minimal length. Defaultvalues and custom fields can be set by individual code shops. C. Codetags should be minimalistic. The quicker it is to jotsomething down, the more likely it is to get jotted. D. The most common use of codetags will only have zero to two fieldsspecified, and these should be the easiest to type and read.Motivation========== * **Various productivity tools can be built around codetags.** See Tools_. * **Encourages consistency.** Historically, a subset of these codetags has been used informally inthe majority of source code in existence, whether in Python or inother languages. Tags have been used in an inconsistent manner withdifferent spellings, semantics, format, and placement. For example,some programmers might include datestamps and/or user identifiers,limit to a single line or not, spell the codetag differently thanothers, etc. * **Encourages adherence to SPOT/DRY principle.** E.g., generating a roadmap dynamically from codetags instead ofkeeping TODOs in sync with separate roadmap document. * **Easy to remember.** All codetags must be concise, intuitive, and semanticallynon-overlapping with others. The format must also be simple. * **Use not required/imposed.** If you don''t use codetags already, there''s no obligation to start,and no risk of affecting code (but see Objections_). A small subsetcan be adopted and the Tools_ will still be useful (a few codetagshave probably already been adopted on an ad-hoc basis anyway). Alsoit is very easy to identify and remove (and possibly record) acodetag that is no longer deemed useful. * **Gives a global view of code.** Tools can be used to generate documentation and reports. * **A logical location for capturing CRCs/Stories/Requirements.** The XP community often does not electronically capture Stories, butcodetags seem like a good place to locate them. * **Extremely lightweight process.** Creating tickets in a tracking system for every thought degradesdevelopment velocity. Even if a ticketing system is employed,codetags are useful for simply containing links to those tickets.Examples======== This shows a simple codetag as commonly found in sources everywhere(with the addition of a trailing ``<>``):: # FIXME: Seems like this loop should be finite. <>while True: ... The following contrived example demonstrates a typical use ofcodetags. It uses some of the available fields to specify theassignees (a pair of programmers with initials *MDE* and *CLE*), theDate of expected completion (*Week 14*), and the Priority of the item(*2*):: # FIXME: Seems like this loop should be finite. <MDE,CLE d:14w p:2>while True: ... This codetag shows a bug with fields describing author, discovery(origination) date, due date, and priority:: # BUG: Crashes if run on Sundays.# <MDE 2005-09-04 d:14w p:2>if day == ''Sunday'': ... Here is a demonstration of how not to use codetags. This has manyproblems: 1) Codetags cannot share a line with code; 2) Missing colonafter mnemonic; 3) A codetag referring to codetags is usually useless,and worse, it is not completable; 4) No need to have a bunch of fieldsfor a trivial codetag; 5) Fields with unknown values (``t:XXX``)should not be used:: i = i + 1 # TODO Add some more codetags.# <JRNewbie 2005-04-03 d:2005-09-03 t:XXX d:14w p:0 s:inprogress>Specification============= This describes the format: syntax, mnemonic names, fields, andsemantics, and also the separate DONE File.General Syntax-------------- Each codetag should be inside a comment, and can be any number oflines. It should not share a line with code. It should match theindentation of surrounding code. The end of the codetag is marked bya pair of angle brackets ``<>`` containing optional fields, which mustnot be split onto multiple lines. It is preferred to have a codetagin ``#`` comments instead of string comments. There can be multiplefields per codetag, all of which are optional. ... NOTE: It may be reasonable to allow fields to fit on multiplelines, but it complicates parsing and defeats minimalism if youuse this many fields. In short, a codetag consists of a mnemonic, a colon, commentary text,an opening angle bracket, an optional list of fields, and a closingangle bracket. E.g., :: # MNEMONIC: Some (maybe multi-line) commentary. <field field ...>Mnemonics--------- The codetags of interest are listed below, using the following format: | ``recommended mnemonic (& synonym list)``| *canonical name*: semantics ``TODO (MILESTONE, MLSTN, DONE, YAGNI, TBD, TOBEDONE)``*To do*: Informal tasks/features that are pending completion. ``FIXME (XXX, DEBUG, BROKEN, REFACTOR, REFACT, RFCTR, OOPS, SMELL, NEEDSWORK, INSPECT)``*Fix me*: Areas of problematic or ugly code needing refactoring orcleanup. ``BUG (BUGFIX)``*Bugs*: Reported defects tracked in bug database. ``NOBUG (NOFIX, WONTFIX, DONTFIX, NEVERFIX, UNFIXABLE, CANTFIX)``*Will Not Be Fixed*: Problems that are well-known but will never beaddressed due to design problems or domain limitations. ``REQ (REQUIREMENT, STORY)``*Requirements*: Satisfactions of specific, formal requirements. ``RFE (FEETCH, NYI, FR, FTRQ, FTR)``*Requests For Enhancement*: Roadmap items not yet implemented. ``IDEA``*Ideas*: Possible RFE candidates, but less formal than RFE. ``??? (QUESTION, QUEST, QSTN, WTF)``*Questions*: Misunderstood details. ``!!! (ALERT)``*Alerts*: In need of immediate attention. ``HACK (CLEVER, MAGIC)``*Hacks*: Temporary code to force inflexible functionality, orsimply a test change, or workaround a known problem. ``PORT (PORTABILITY, WKRD)``*Portability*: Workarounds specific to OS, Python version, etc. ``CAVEAT (CAV, CAVT, WARNING, CAUTION)``*Caveats*: Implementation details/gotchas that stand out asnon-intuitive. ``NOTE (HELP)``*Notes*: Sections where a code reviewer found something that needsdiscussion or further investigation. ``FAQ``*Frequently Asked Questions*: Interesting areas that requireexternal explanation. ``GLOSS (GLOSSARY)``*Glossary*: Definitions for project glossary. ``SEE (REF, REFERENCE)``*See*: Pointers to other code, web link, etc. ``TODOC (DOCDO, DODOC, NEEDSDOC, EXPLAIN, DOCUMENT)``*Needs Documentation*: Areas of code that still need to bedocumented. ``CRED (CREDIT, THANKS)``*Credits*: Accreditations for external provision of enlightenment. ``STAT (STATUS)``*Status*: File-level statistical indicator of maturity of thisfile. ``RVD (REVIEWED, REVIEW)``*Reviewed*: File-level indicator that review was conducted. File-level codetags might be better suited as properties in therevision control system, but might still be appropriately specified ina codetag. Some of these are temporary (e.g., ``FIXME``) while others arepersistent (e.g., ``REQ``). A mnemonic was chosen over a synonymusing three criteria: descriptiveness, length (shorter is better),commonly used. Choosing between ``FIXME`` and ``XXX`` is difficult. ``XXX`` seems tobe more common, but much less descriptive. Furthermore, ``XXX`` is auseful placeholder in a piece of code having a value that is unknown.Thus ``FIXME`` is the preferred spelling. `Sun says`__ that ``XXX``and ``FIXME`` are slightly different, giving ``XXX`` higher severity.However, with decades of chaos on this topic, and too many millions ofdevelopers who won''t be influenced by Sun, it is easy to rightly callthem synonyms. __ http://java.sun.com/docs/codeconv/ht....doc9.html#395 ``DONE`` is always a completed ``TODO`` item, but this should probablybe indicated through the revision control system and/or a completionrecording mechanism (see `DONE File`_). It may be a useful metric to count ``NOTE`` tags: a high count mayindicate a design (or other) problem. But of course the majority ofcodetags indicate areas of code needing some attention. An ``FAQ`` is probably more appropriately documented in a wiki whereusers can more easily view and contribute.Fields------ All fields are optional. The proposed standard fields are describedin this section. Note that upper case field characters are intendedto be replaced. The *Originator/Assignee* and *Origination Date/Week* fields are themost common and don''t usually require a prefix. ... NOTE: the colon after the prefix is a new addition that becamenecessary when it was pointed out that a "codename" field (with nodigits) such as "cTiger" would be indistinguishable from a username.<MDE 2005-9-24> ... NOTE: This section started out with just assignee and due week. Ithas grown into a lot of fields by request. It is still probablybest to use a tracking system for any items that deserve it, andnot duplicate everything in a codetag (field). <MDE> This lengthy list of fields is liable to scare people (the intendedminimalists) away from adopting codetags, but keep in mind that theseonly exist to support programmers who either 1) like to keep ``BUG``or ``RFE`` codetags in a complete form, or 2) are using codetags astheir complete and only tracking system. In other words, many ofthese fields will be used very rarely. They are gathered largely fromindustry-wide conventions, and example sources include `GCCBugzilla`__ and `Python''s SourceForge`__ tracking systems. ... ???: Maybe codetags inside packages (__init__.py files) could havespecial global significance. <MDE> __ http://gcc.gnu.org/bugzilla/__ http://sourceforge.net/tracker/?group_id=5470 ``AAA[,BBB]...``List of *Originator* or *Assignee* initials (the contextdetermines which unless both should exist). It is also okay touse usernames such as ``MicahE`` instead of initials. Initials(in upper case) are the preferred form. ``a:AAA[,BBB]...``List of *Assignee* initials. This is necessary only in (rare)cases where a codetag has both an assignee and an originator, andthey are different. Otherwise the ``a:`` prefix is omitted, andcontext determines the intent. E.g., ``FIXME`` usually has an*Assignee*, and ``NOTE`` usually has an *Originator*, but if a``FIXME`` was originated (and initialed) by a reviewer, then theassignee''s initials would need a ``a:`` prefix. ``YYYY[-MM[-DD]]`` or ``WW[.D]w``The *Origination Date* indicating when the comment was added, in`ISO 8601`_ format (digits and hyphens only). Or *OriginationWeek*, an alternative form for specifying an *Origination Date*.A day of the week can be optionally specified. The ``w`` suffixis necessary for distinguishing from a date. ``d:YYYY[-MM[-DD]]`` or ``d:WW[.D]w``*Due Date (d)* target completion (estimate). Or *Due Week (d)*,an alternative to specifying a *Due Date*. ``p:N``*Priority (p)* level. Range (N) is from 0..3 with 3 being thehighest. 0..3 are analogous to low, medium, high, andshowstopper/critical. The *Severity* field could be factored intothis single number, and doing so is recommended since having bothis subject to varying interpretation. The range and order shouldbe customizable. The existence of this field is important for anytool that itemizes codetags. Thus a (customizable) default valueshould be supported. ``t:NNNN``*Tracker (t)* number corresponding to associated Ticket ID inseparate tracking system. The following fields are also available but expected to be lesscommon. ``c:AAAA``*Category (c)* indicating some specific area affected by thisitem. ``s:AAAA``*Status (s)* indicating state of item. Examples are "unexplored","understood", "inprogress", "fixed", "done", "closed". Note thatwhen an item is completed it is probably better to remove thecodetag and record it in a `DONE File`_. ``i:N``Development cycle *Iteration (i)*. Useful for grouping codetags intocompletion target groups. ``r:N``Development cycle *Release (r)*. Useful for grouping codetags intocompletion target groups. .. NOTE: SourceForge does not recognize a severity and I thinkthat *Priority* (along with separate RFE codetags) shouldencompass and obviate *Severity*. <MDE> .. NOTE: The tools will need an ability to sort codetags in orderof targeted completion. I feel that *Priority* should be aunique, lone indicator of that addressability order. Othercategories such as *Severity*, *Customer Importance*, etc. arerelated to business logic and should not be recognized by thecodetag tools. If some groups want to have such logic, then itis best factored (externally) into a single value (priority)that can determine an ordering of actionable items. <MDE> To summarize, the non-prefixed fields are initials and originationdate, and the prefixed fields are: assignee (a), due (d), priority(p),tracker (t), category (c), status (s), iteration (i), and release(r). It should be possible for groups to define or add their own fields,and these should have upper case prefixes to distinguish them from thestandard set. Examples of custom fields are *Operating System (O)*,*Severity (S)*, *Affected Version (A)*, *Customer (C)*, etc.DONE File--------- Some codetags have an ability to be *completed* (e.g., ``FIXME``,``TODO``, ``BUG``). It is often important to retain completed itemsby recording them with a completion date stamp. Such completed itemsare best stored in a single location, global to a project (or maybe apackage). The proposed format is most easily described by an example,say ``~/src/fooproj/DONE``:: # TODO: Recurse into subdirs only on blue# moons. <MDE 2003-09-26>[2005-09-26 Oops, I underestimated this one a bit. Should haveused Warsaw''s First Law!] # FIXME: ...... You can see that the codetag is copied verbatim from the originalsource file. The date stamp is then entered on the following linewith an optional post-mortem commentary. The entry is terminated by ablank line (``\n\n``). It may sound burdensome to have to delete codetag lines every time onegets completed. But in practice it is quite easy to setup a Vim orEmacs mapping to auto-record a codetag deletion in this format (sansthe commentary).Tools===== Currently, programmers (and sometimes analysts) typically use *grep*to generate a list of items corresponding to a single codetag.However, various hypothetical productivity tools could take advantageof a consistent codetag format. Some example tools follow. ... NOTE: Codetag tools are mostly unimplemented (but I''m gettingstarted!) <MDE> Document GeneratorPossible docs: glossary, roadmap, manpages Codetag HistoryTrack (with revision control system interface) when a ``BUG`` tag(or any codetag) originated/resolved in a code section Code StatisticsA project Health-O-Meter Codetag LintNotify of invalid use of codetags, and aid in porting to codetags Story Manager/BrowserAn electronic means to replace XP notecards. In MVC terms, thecodetag is the Model, and the Story Manager could be a graphicalViewer/Controller to do visual rearrangement, prioritization, andassignment, milestone management. Any Text EditorUsed for changing, removing, adding, rearranging, recordingcodetags. There are some tools already in existence that take advantage of asmaller set of pseudo-codetags (see References_). There is also anexample codetags implementation under way, known as the `CodetagProject`__. __ http://tracos.org/codetagObjections========== :Objection: Extreme Programming argues that such codetags should notever exist in code since the code is the documentation. :Defense: Maybe you should put the codetags in the unit test filesinstead. Besides, it''s tough to generate documentation fromuncommented source code. ---- :Objection: Too much existing code has not followed proposedguidelines. :Defense: [Simple] utilities (*ctlint*) could convert existing codes. ---- :Objection: Causes duplication with tracking system. :Defense: Not really, unless fields are abused. If an item exists inthe tracker, a simple ticket number in the codetag tracker fieldis sufficient. Maybe a duplicated title would be acceptable.Furthermore, it''s too burdensome to have a ticket filed for everyitem that pops into a developer''s mind on-the-go. Additionally,the tracking system could possibly be obviated for simple or smallprojects that can reasonably fit the relevant data into a codetag. ---- :Objection: Codetags are ugly and clutter code. :Defense: That is a good point. But I''d still rather have such infoin a single place (the source code) than various other documents,likely getting duplicated or forgotten about. The completedcodetags can be sent off to the `DONE File`_, or to the bitbucket. ---- :Objection: Codetags (and allcomments) get out of date. :Defense: Not so much if other sources (externally visibledocumentation) depend on their being accurate. ---- :Objection: Codetags tend to only rarely have estimated completiondates of any sort. OK, the fields are optional, but you want tosuggest fields that actually will be widely used. :Defense: If an item is inestimable don''t bother with specifying adate field. Using tools to display items with order and/or colorby due date and/or priority, it is easier to make estimates.Having your roadmap be a dynamic reflection of your codetags makesyou much more likely to keep the codetags accurate. ---- :Objection: Named variables for the field parameters in the ``<>``should be used instead of cryptic one-character prefixes. I.e.,<MDE p:3> should rather be <author=MDE, priority=3>. :Defense: It is just too much typing/verbosity to spell out fields. Iargue that ``p:3 i:2`` is as readable as ``priority=3,iteration=2`` and is much more likely to by typed and remembered(see bullet C in Philosophy_). In this case practicality beatspurity. There are not many fields to keep track of so one letterprefixes are suitable. ---- :Objection: Synonyms should be deprecated since it is better to have asingle way to spell something. :Defense: Many programmers prefer short mnemonic names, especially incomments. This is why short mnemonics were chosen as the primarynames. However, others feel that an explicit spelling is lessconfusing and less prone to error. There will always be two campson this subject. Thus synonyms (and complete, full spellings)should remain supported. ---- :Objection: It is cruel to use [for mnemonics] opaque acronyms andabbreviations which drop vowels; it''s hard to figure these thingsout. On that basis I hate: MLSTN RFCTR RFE FEETCH, NYI, FR, FTRQ,FTR WKRD RVDBY :Defense: Mnemonics are preferred since they are pretty easy toremember and take up less space. If programmers didn''t likedropping vowels we would be able to fit very little code on aline. The space is important for those who write comments thatoften fit on a single line. But when using a canon everywhere itis much less likely to get something to fit on a line. ---- :Objection: It takes too long to type the fields. :Defense: Then don''t use (most or any of) them, especially if you''rethe only programmer. Terminating a codetag with ``<>`` is a smallchore, and in doing so you enable the use of the proposed tools.Editor auto-completion of codetags is also useful: You canprogram your editor to stamp a template (e.g. ``# FIXME . <MDE{date}>``) with just a keystroke or two. ---- :Objection: *WorkWeek* is an obscure and uncommon time unit. :Defense: That''s true but it is a highly suitable unit of granularityfor estimation/targeting purposes, and it is very compact. The`ISO 8601`_ is widely understood but allows you to only specifyeither a specific day (restrictive) or month (broad). ---- :Objection: I aesthetically dislike for the comment to be terminatedwith <> in the empty field case. :Defense: It is necessary to have a terminator since codetags may befollowed by non-codetag comments. Or codetags could be limited toa single line, but that''s prohibitive. I can''t think of anysingle-character terminator that is appropriate and significantlybetter than <>. Maybe ``@`` could be a terminator, but then mostcodetags will have an unnecessary @. ---- :Objection: I can''t use codetags when writing HTML, or lessspecifically, XML. Maybe ``@fields@`` would be a better than``<fields>`` as the delimiters. :Defense: Maybe you''re right, but ``<>`` looks nicer wheneverapplicable. XML/SGML could use ``@`` while more commonprogramming languages stick to ``<>``.References========== Some other tools have approached defining/exploiting codetags.See http://tracos.org/codetag/wiki/Links. ... _wiki: http://tracos.org/codetag/wiki/Pep... _ISO 8601: http://en.wikipedia.org/wiki/ISO_8601... _c2: http://c2.com/cgi/wiki?FixmeComment ...Local Variables:mode: indented-textindent-tabs-mode: nilsentence-end-double-space: tfill-column: 70End:推荐答案Revision: 1.2Revision: 1.2 Last-Modified:Last-Modified:Date: 2005/09/26 19:56:53Date: 2005/09/26 19:56:53 这篇关于PEP 350：标准码的文章就介绍到这了，希望我们推荐的答案对大家有所帮助，也希望大家多多支持！