Rejection Notice

This PEP has been rejected. While the community may be interested, there is no desire to make the standard library conform to this standard.

Abstract

This informational PEP aims to provide guidelines for consistent use of codetags, which would enable the construction of standard utilities to take advantage of the codetag information, as well as making Python code more uniform across projects. Codetags also represent a very lightweight programming micro-paradigm and become useful for project management, documentation, change tracking, and project health monitoring. This is submitted as a PEP because its ideas are thought to be Pythonic, although the concepts are not unique to Python programming. Herein are the definition of codetags, the philosophy behind them, a motivation for standardized conventions, some examples, a specification, a toolset description, and possible objections 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 serve as reminders of sections of code that need closer inspection or review. Examples of markup include FIXME, TODO, XXX, BUG, but there many more in wide use in existing software. Such markup will henceforth be referred to as codetags. These codetags may show up in application code, unit tests, scripts, general documentation, or wherever suitable.

Codetags have been under discussion and in use (hundreds of codetags in 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 be useful for you.

1. As much information as possible should be contained inside the source code (application code or unit tests). This along with use of codetags impedes duplication. Most documentation can be generated from that source code; e.g., by using help2man, man2html, docutils, epydoc/pydoc, ctdoc, etc.
2. Information should be almost never duplicated – it should be recorded in a single original format and all other locations should be automatically generated from the original, or simply be referenced. This is famously known as the Single Point Of Truth (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 output formats. People want documentation in many forms. It is thus important to have a documentation system that can generate all of these.
4. The developers are the documentation team. They write the code and should know the code the best. There should not be a dedicated, disjoint documentation team for any non-huge project.
5. Plain text (with non-invasive markup) is the best format for writing anything. All other formats are to be generated from the plain text.

Codetag design was influenced by the following goals:

1. Comments should be short whenever possible.
2. Codetag fields should be optional and of minimal length. Default values and custom fields can be set by individual code shops.
3. Codetags should be minimalistic. The quicker it is to jot something down, the more likely it is to get jotted.
4. The most common use of codetags will only have zero to two fields specified, 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 in the majority of source code in existence, whether in Python or in other languages. Tags have been used in an inconsistent manner with different 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 than others, etc.

• Encourages adherence to SPOT/DRY principle.

  E.g., generating a roadmap dynamically from codetags instead of keeping TODOs in sync with separate roadmap document.

• Easy to remember.

  All codetags must be concise, intuitive, and semantically non-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 subset can be adopted and the Tools will still be useful (a few codetags have probably already been adopted on an ad-hoc basis anyway). Also it is very easy to identify and remove (and possibly record) a codetag 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, but codetags seem like a good place to locate them.

• Extremely lightweight process.

  Creating tickets in a tracking system for every thought degrades development 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 of codetags. It uses some of the available fields to specify the assignees (a pair of programmers with initials MDE and CLE), the Date 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 many problems: 1) Codetags cannot share a line with code; 2) Missing colon after mnemonic; 3) A codetag referring to codetags is usually useless, and worse, it is not completable; 4) No need to have a bunch of fields for 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>