added PEP 350, "Codetags", by Micah Elliott
This commit is contained in:
parent
303740df18
commit
43f0aa8d20
|
@ -105,6 +105,7 @@ Index by Category
|
|||
S 345 Metadata for Python Software Packages 1.2 Jones
|
||||
P 347 Migrating the Python CVS to Subversion von Löwis
|
||||
S 349 Allow str() to return unicode strings Schemenauer
|
||||
I 350 Codetags Elliott
|
||||
S 754 IEEE 754 Floating Point Special Values Warnes
|
||||
|
||||
Finished PEPs (done, implemented in CVS)
|
||||
|
@ -394,6 +395,7 @@ Numerical Index
|
|||
P 347 Migrating the Python CVS to Subversion von Löwis
|
||||
SR 348 Exception Reorganization for Python 3.0 Cannon
|
||||
S 349 Allow str() to return unicode strings Schemenauer
|
||||
I 350 Codetags Elliott
|
||||
SR 666 Reject Foolish Indentation Creighton
|
||||
S 754 IEEE 754 Floating Point Special Values Warnes
|
||||
I 3000 Python 3.0 Plans Kuchling, Cannon
|
||||
|
@ -438,6 +440,7 @@ Owners
|
|||
Dubner, Michael P. dubnerm@mindless.com
|
||||
Dubois, Paul F. paul@pfdubois.com
|
||||
Eby, Phillip J. pje@telecommunity.com
|
||||
Elliott, Micah mde at tracos.org
|
||||
Epler, Jeff jepler@unpythonic.net
|
||||
Eppstein, David eppstein@ics.uci.edu
|
||||
Evans, Clark C. cce@clarkevans.com
|
||||
|
|
|
@ -0,0 +1,432 @@
|
|||
PEP: 350
|
||||
Title: Codetags
|
||||
Version: $Revision$
|
||||
Last-Modified: $Date$
|
||||
Author: Micah Elliott <mde at tracos.org>
|
||||
Status: Draft
|
||||
Type: Informational
|
||||
Content-Type: text/x-rst
|
||||
Created: 27-Jun-2005
|
||||
Post-History: 10-Aug-2005
|
||||
|
||||
|
||||
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 I feel its ideas are
|
||||
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, 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.
|
||||
|
||||
|
||||
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 the *SPOT* 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. Whenever information is subject to (and suited for) user
|
||||
feedback/input (e.g., FAQ, RFC, PEP), it should be contained in a
|
||||
**repository** (e.g. a wiki, usenet, or mailing lists).
|
||||
|
||||
5. There should not be a dedicated, disjoint **documentation team**
|
||||
for any non-huge project. The developers writing the code know the
|
||||
code best, and they should be the ones to describe it.
|
||||
|
||||
6. **Plain text** (with non-invasive markup) is the best form of
|
||||
writing anything. All other formats are to be generated from the
|
||||
plain text.
|
||||
|
||||
7. **Revision control** should be used for almost everything. And
|
||||
modifications should be checked in at least daily.
|
||||
|
||||
|
||||
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 if a Codetag is no longer
|
||||
deemed useful. Then it is effectively *committed* and recorded by
|
||||
revision control simply by checking in.
|
||||
|
||||
* **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 ``<>``)::
|
||||
|
||||
def foo():
|
||||
# FIXME: Seems like this loop should be finite. <>
|
||||
while True: ...
|
||||
|
||||
The following contrived example demonstrates a more common use of
|
||||
Codetagging. It uses some of the available fields to specify the
|
||||
owners (a pair of developers with initials *MDE* and *CLE*), the Work
|
||||
Week of expected completion (*w14*), and the priority of the item
|
||||
(*p2*)::
|
||||
|
||||
def foo():
|
||||
# FIXME: Seems like this loop should be finite. <MDE,CLE w14 p2>
|
||||
while True: ...
|
||||
|
||||
|
||||
Specification
|
||||
=============
|
||||
|
||||
This describes the format: syntax, mnemonic names, fields, and
|
||||
semantics.
|
||||
|
||||
|
||||
General Syntax
|
||||
--------------
|
||||
|
||||
Each Codetag should be inside a comment, and can be any number of
|
||||
lines. It should match the indentation of surrounding code. The end
|
||||
of the Codetag is marked by a pair of angle brackets ``<>`` containing
|
||||
optional fields, which must not be split onto multiple lines.
|
||||
|
||||
.. NOTE: This PEP's text originally did not conform to the "inside a
|
||||
comment" rule. Documents can have comments too! I fixed that.
|
||||
-Ed. <DJG 2005-09-14>
|
||||
|
||||
There can be multiple fields per Codetag, all of which are optional.
|
||||
|
||||
In short, a Codetag consists of a mnemonic, a colon, commentary text,
|
||||
an opening angle bracket, an optional list of fields, and a closing
|
||||
angle bracket. E.g., ::
|
||||
|
||||
# MNEMONIC: Some (maybe multi-line) commentary. <field field ...>
|
||||
|
||||
.. FIXME: Add completion vs target date?? <MDE>
|
||||
|
||||
|
||||
Mnemonics
|
||||
---------
|
||||
|
||||
The Codetags of interest are listed below, using the following format:
|
||||
|
||||
| ``recommended mnemonic (& synonym list)``
|
||||
| *canonical name*: semantics
|
||||
|
||||
``FIXME (XXX, DEBUG, BROKEN, RFCTR, OOPS, SMELL, NEEDSWORK)``
|
||||
*Fix me*: Areas of problematic or ugly code needing refactoring or
|
||||
cleanup.
|
||||
|
||||
``NOFIX (DONTFIX, NEVERFIX, NOBUG)``
|
||||
*Will Not Be Fixed*: Problems that are well-known but will never be
|
||||
addressed due to design problems or domain limitations.
|
||||
|
||||
``!!! (ALERT)``
|
||||
*Alerts*: In need of immediate attention.
|
||||
|
||||
``GLOSS (GLOSSARY)``
|
||||
*Glossary*: Definitions for project glossary.
|
||||
|
||||
``DOC (DOCUMENT)``
|
||||
*Needs Documentation*: Areas of code that still need to be
|
||||
documented.
|
||||
|
||||
``REQ (REQUIREMENT, STORY)``
|
||||
*Requirements*: Satisfactions of specific, formal requirements.
|
||||
|
||||
``IDEA``
|
||||
*Ideas*: Possible RFE candidates, but less formal than RFE.
|
||||
|
||||
``BUG (BUGFIX)``
|
||||
*Bugs*: Reported defects tracked in bug database.
|
||||
|
||||
``NOTE (HELP)``
|
||||
*Notes*: Sections where a code reviewer found something that needs
|
||||
discussion or further investigation.
|
||||
|
||||
``SEE (REF)``
|
||||
*See*: Pointers to other code, web link, etc.
|
||||
|
||||
``STAT (STATUS)``
|
||||
*Status*: File-level statistical indicator of work needing done on
|
||||
this file.
|
||||
|
||||
``RFE (FEETCH, NYI, FR, FTRQ, FTR)``
|
||||
*Requests For Enhancement*: Roadmap items not yet implemented.
|
||||
|
||||
``HACK (CLEVER)``
|
||||
*Hacks*: Temporary code to force inflexible functionality, or
|
||||
simply a test change, or workaround a known problem.
|
||||
|
||||
``CAV (CAVEAT, WARNING, CAUTION)``
|
||||
*Caveats*: Implementation details/gotchas that stand out as
|
||||
non-intuitive.
|
||||
|
||||
``RVDBY (REVIEWED)``
|
||||
*Reviewed By*: File-level indicator of programmer(s) who performed
|
||||
recent code review.
|
||||
|
||||
``??? (QUESTION, QUEST, QSTN, WTF)``
|
||||
*Questions*: Misunderstood details.
|
||||
|
||||
``CRED (CREDIT, THANKS)``
|
||||
*Credits*: Accreditations for external provision of enlightenment.
|
||||
|
||||
``TODO (MLSTN, DONE, YAGNI, TBD, TOBEDONE)``
|
||||
*To do*: Informal tasks/features that are pending completion.
|
||||
|
||||
.. NOTE: TBD and TOBEDONE belong here, not with FIXME <DJG 2005-09-18>
|
||||
|
||||
``PORT (PORTABILITY, WKRD)``
|
||||
*Portability*: Workarounds specific to OS, Python version, etc.
|
||||
|
||||
``FAQ``
|
||||
*Frequently Asked Questions*: Interesting areas that require
|
||||
external explanation.
|
||||
|
||||
File-level Codetags might be better suited as properties in the
|
||||
revision control system.
|
||||
|
||||
Some of these are temporary (e.g., ``FIXME``) while others are
|
||||
persistent (e.g., ``REQ``). Synonyms should probably be deprecated in
|
||||
the interest of minimalism and consistency. I chose a mnemonic over a
|
||||
synonym using three criteria: descriptiveness, length (shorter is
|
||||
better), commonly used.
|
||||
|
||||
Choosing between ``FIXME`` and ``XXX`` is difficult. ``XXX`` seems to
|
||||
be more common, but much less descriptive. Furthermore, ``XXX`` is a
|
||||
useful placeholder in a piece of code having a value that is unknown.
|
||||
`Sun says`__ that ``XXX`` and ``FIXME`` are slightly different, giving
|
||||
``XXX`` higher severity.
|
||||
|
||||
__ http://java.sun.com/docs/codeconv/html/CodeConventions.doc9.html#395
|
||||
|
||||
``DONE`` is always a completed ``TODO`` item, but this should probably
|
||||
be indicated through the revision control system.
|
||||
|
||||
It may be a useful metric to count ``NOTE`` tags: a high count may
|
||||
indicate a problem.
|
||||
|
||||
``FAQ`` is probably more appropriately documented in a wiki where
|
||||
users can more easily contribute.
|
||||
|
||||
|
||||
Fields
|
||||
------
|
||||
|
||||
All fields are optional. It should be possible for groups to define or
|
||||
add their own, but the proposed standard fields are as follows:
|
||||
|
||||
``pN``
|
||||
*Priority* level. Range is from 0..3 with 3 being the highest. A
|
||||
*Severity* field could also exist, or it could be factored into
|
||||
this single number.
|
||||
|
||||
``iN``
|
||||
Development cycle *Iteration*. Useful for grouping Codetags into
|
||||
completion target groups.
|
||||
|
||||
``XXX[,YYY]...``
|
||||
List of *Initials* of owners of completion responsibility. There
|
||||
should be no digits in initials.
|
||||
|
||||
.. ???: should initials be uppercase or lowercase? I prefer
|
||||
uppercase, personally. <DJG 2005-09-14>
|
||||
|
||||
.. NOTE: I agree that uppercase is better but I'll leave that open
|
||||
to users. <MDE>
|
||||
|
||||
``wWW[.D]``
|
||||
*Workweek* target completion (estimate). A day of the week can be
|
||||
optionally specified. Origination and completion are freebies
|
||||
with revision control.
|
||||
|
||||
.. ???: Since *workweek* and *date* are redundant we might want to
|
||||
decide on one or other. Date is longer but is better
|
||||
understood by most so the likely keeper. <MDE>
|
||||
|
||||
.. NOTE: *Workweek* indicates a completion estimate, but *date*
|
||||
simply indicates when the comment was added. They're not
|
||||
redundant. However, rather than workweek (which isn't used
|
||||
much in my experience), it might be better to have a "c"
|
||||
(completion estimate) tag with date content.
|
||||
|
||||
``yyyy[-mm[-dd]]``
|
||||
The *Date* the comment was added, in `ISO 8601`_ format (digits
|
||||
and hyphens only).
|
||||
|
||||
|
||||
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 advantage
|
||||
of a consistent Codetag format. Some example tools follow.
|
||||
|
||||
.. NOTE: Codetag tools are mostly unimplemented (but I'm getting
|
||||
started!) <MDE>
|
||||
|
||||
Document Generator
|
||||
Possible docs: glossary, roadmap, manpages
|
||||
|
||||
Codetag History
|
||||
Track (with revision control system interface) when a ``BUG`` tag
|
||||
(or any codetag) originated/resolved in a code section
|
||||
|
||||
Code Statistics
|
||||
A project Health-O-Meter
|
||||
|
||||
Codetag Lint
|
||||
Notify of invalid use of Codetags, and aid in porting to Codetag
|
||||
|
||||
Story Manager/Browser
|
||||
An electronic means to replace XP notecards. In MVC terms, the
|
||||
Codetag is the Model, and the Story Manager could be a graphical
|
||||
Viewer/Controller to do visual rearrangement, prioritization, and
|
||||
assignment, milestone management.
|
||||
|
||||
Any Text Editor
|
||||
Used for changing, removing, adding, rearranging Codetags.
|
||||
|
||||
There are some tools already in existence that take advantage of a
|
||||
smaller set of pseudo-Codetags (see References_).
|
||||
|
||||
|
||||
Objections
|
||||
==========
|
||||
|
||||
:Objection: Extreme Programming argues that such Codetags should not
|
||||
ever exist in code since the code is the documentation.
|
||||
|
||||
:Defense: Maybe put the Codetags in the unit test files instead.
|
||||
Besides, it's tough to generate documentation from uncommented
|
||||
source code.
|
||||
|
||||
----
|
||||
|
||||
:Objection: Too much existing code has not followed proposed
|
||||
guidelines.
|
||||
|
||||
:Defense: [Simple] utilities (*ctlint*) could convert existing codes.
|
||||
|
||||
----
|
||||
|
||||
:Objection: Causes duplication with tracking system.
|
||||
|
||||
:Defense: Not really. If an item exists in the tracker, a simple
|
||||
ticket number as the Codetag commentary is sufficient. Maybe a
|
||||
duplicated title would be acceptable. Furthermore, it's too
|
||||
burdensome to have a ticket filed for every item that pops into a
|
||||
developer's mind on-the-go.
|
||||
|
||||
----
|
||||
|
||||
:Objection: Codetags are ugly and clutter code.
|
||||
|
||||
:Defense: That is a good point. But I'd still rather have such info
|
||||
in a single place (the source code) than various other documents,
|
||||
likely getting duplicated or forgotten about.
|
||||
|
||||
----
|
||||
|
||||
:Objection: Codetags (and all comments) get out of date.
|
||||
|
||||
:Defense: Not so much if other sources (externally visible
|
||||
documentation) depend on them being accurate.
|
||||
|
||||
|
||||
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
|
||||
|
||||
..
|
||||
Local Variables:
|
||||
mode: indented-text
|
||||
indent-tabs-mode: nil
|
||||
sentence-end-double-space: t
|
||||
fill-column: 70
|
||||
End:
|
Loading…
Reference in New Issue