[Python-checkins] python/nondist/peps pep-0350.txt, NONE, 1.1 pep-0000.txt, 1.343, 1.344
goodger@users.sourceforge.net
goodger at users.sourceforge.net
Sun Sep 18 17:10:14 CEST 2005
Update of /cvsroot/python/python/nondist/peps
In directory sc8-pr-cvs1.sourceforge.net:/tmp/cvs-serv28258
Modified Files:
pep-0000.txt
Added Files:
pep-0350.txt
Log Message:
added PEP 350, "Codetags", by Micah Elliott
--- NEW FILE: pep-0350.txt ---
PEP: 350
Title: Codetags
Version: $Revision: 1.1 $
Last-Modified: $Date: 2005/09/18 15:10:08 $
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:
Index: pep-0000.txt
===================================================================
RCS file: /cvsroot/python/python/nondist/peps/pep-0000.txt,v
retrieving revision 1.343
retrieving revision 1.344
diff -u -d -r1.343 -r1.344
--- pep-0000.txt 26 Aug 2005 06:01:04 -0000 1.343
+++ pep-0000.txt 18 Sep 2005 15:10:08 -0000 1.344
@@ -105,6 +105,7 @@
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 @@
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 @@
Dubner, Michael P. dubnerm at mindless.com
Dubois, Paul F. paul at pfdubois.com
Eby, Phillip J. pje at telecommunity.com
+ Elliott, Micah mde at tracos.org
Epler, Jeff jepler at unpythonic.net
Eppstein, David eppstein at ics.uci.edu
Evans, Clark C. cce at clarkevans.com
More information about the Python-checkins
mailing list