PEP 350: Codetags


M

Micah Elliott

Please read/comment/vote. This circulated as a pre-PEP proposal
submitted to c.l.py on August 10, but has changed quite a bit since
then. 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: 350
Title: Codetags
Version: $Revision: 1.2 $
Last-Modified: $Date: 2005/09/26 19:56:53 $
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, 26-Sep-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 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:

A. Comments should be short whenever possible.

B. Codetag fields should be optional and of minimal length. Default
values and custom fields can be set by individual code shops.

C. Codetags should be minimalistic. The quicker it is to jot
something down, the more likely it is to get jotted.

D. 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>


Specification
=============

This describes the format: syntax, mnemonic names, fields, and
semantics, and also the separate DONE File.


General Syntax
--------------

Each codetag should be inside a comment, and can be any number of
lines. It should not share a line with code. 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. It is preferred to have a codetag
in ``#`` comments instead of string comments. There can be multiple
fields per codetag, all of which are optional.

... NOTE: It may be reasonable to allow fields to fit on multiple
lines, but it complicates parsing and defeats minimalism if you
use 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 closing
angle 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 or
cleanup.

``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 be
addressed 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, or
simply 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 as
non-intuitive.

``NOTE (HELP)``
*Notes*: Sections where a code reviewer found something that needs
discussion or further investigation.

``FAQ``
*Frequently Asked Questions*: Interesting areas that require
external 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 be
documented.

``CRED (CREDIT, THANKS)``
*Credits*: Accreditations for external provision of enlightenment.

``STAT (STATUS)``
*Status*: File-level statistical indicator of maturity of this
file.

``RVD (REVIEWED, REVIEW)``
*Reviewed*: File-level indicator that review was conducted.

File-level codetags might be better suited as properties in the
revision control system, but might still be appropriately specified in
a codetag.

Some of these are temporary (e.g., ``FIXME``) while others are
persistent (e.g., ``REQ``). A mnemonic was chosen 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.
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 of
developers who won't be influenced by Sun, it is easy to rightly call
them synonyms.

__ 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 and/or a completion
recording mechanism (see `DONE File`_).

It may be a useful metric to count ``NOTE`` tags: a high count may
indicate a design (or other) problem. But of course the majority of
codetags indicate areas of code needing some attention.

An ``FAQ`` is probably more appropriately documented in a wiki where
users can more easily view and contribute.


Fields
------

All fields are optional. The proposed standard fields are described
in this section. Note that upper case field characters are intended
to be replaced.

The *Originator/Assignee* and *Origination Date/Week* fields are the
most common and don't usually require a prefix.

... NOTE: the colon after the prefix is a new addition that became
necessary when it was pointed out that a "codename" field (with no
digits) such as "cTiger" would be indistinguishable from a username.
<MDE 2005-9-24>

... NOTE: This section started out with just assignee and due week. It
has grown into a lot of fields by request. It is still probably
best to use a tracking system for any items that deserve it, and
not duplicate everything in a codetag (field). <MDE>

This lengthy list of fields is liable to scare people (the intended
minimalists) away from adopting codetags, but keep in mind that these
only exist to support programmers who either 1) like to keep ``BUG``
or ``RFE`` codetags in a complete form, or 2) are using codetags as
their complete and only tracking system. In other words, many of
these fields will be used very rarely. They are gathered largely from
industry-wide conventions, and example sources include `GCC
Bugzilla`__ and `Python's SourceForge`__ tracking systems.

... ???: Maybe codetags inside packages (__init__.py files) could have
special global significance. <MDE>

__ http://gcc.gnu.org/bugzilla/
__ http://sourceforge.net/tracker/?group_id=5470

``AAA[,BBB]...``
List of *Originator* or *Assignee* initials (the context
determines which unless both should exist). It is also okay to
use 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, and
they are different. Otherwise the ``a:`` prefix is omitted, and
context 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 the
assignee'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 *Origination
Week*, an alternative form for specifying an *Origination Date*.
A day of the week can be optionally specified. The ``w`` suffix
is 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 the
highest. 0..3 are analogous to low, medium, high, and
showstopper/critical. The *Severity* field could be factored into
this single number, and doing so is recommended since having both
is subject to varying interpretation. The range and order should
be customizable. The existence of this field is important for any
tool that itemizes codetags. Thus a (customizable) default value
should be supported.

``t:NNNN``
*Tracker (t)* number corresponding to associated Ticket ID in
separate tracking system.

The following fields are also available but expected to be less
common.

``c:AAAA``
*Category (c)* indicating some specific area affected by this
item.

``s:AAAA``
*Status (s)* indicating state of item. Examples are "unexplored",
"understood", "inprogress", "fixed", "done", "closed". Note that
when an item is completed it is probably better to remove the
codetag and record it in a `DONE File`_.

``i:N``
Development cycle *Iteration (i)*. Useful for grouping codetags into
completion target groups.

``r:N``
Development cycle *Release (r)*. Useful for grouping codetags into
completion target groups.

.. NOTE: SourceForge does not recognize a severity and I think
that *Priority* (along with separate RFE codetags) should
encompass and obviate *Severity*. <MDE>

.. NOTE: The tools will need an ability to sort codetags in order
of targeted completion. I feel that *Priority* should be a
unique, lone indicator of that addressability order. Other
categories such as *Severity*, *Customer Importance*, etc. are
related to business logic and should not be recognized by the
codetag tools. If some groups want to have such logic, then it
is 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 origination
date, 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 the
standard 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 items
by recording them with a completion date stamp. Such completed items
are best stored in a single location, global to a project (or maybe a
package). 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 have
used Warsaw's First Law!]

# FIXME: ...
...

You can see that the codetag is copied verbatim from the original
source file. The date stamp is then entered on the following line
with an optional post-mortem commentary. The entry is terminated by a
blank line (``\n\n``).

It may sound burdensome to have to delete codetag lines every time one
gets completed. But in practice it is quite easy to setup a Vim or
Emacs mapping to auto-record a codetag deletion in this format (sans
the 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 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 codetags

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, recording
codetags.

There are some tools already in existence that take advantage of a
smaller set of pseudo-codetags (see References_). There is also an
example codetags implementation under way, known as the `Codetag
Project`__.

__ http://tracos.org/codetag


Objections
==========

:Objection: Extreme Programming argues that such codetags should not
ever exist in code since the code is the documentation.

:Defense: Maybe you should 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, unless fields are abused. If an item exists in
the tracker, a simple ticket number in the codetag tracker field
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. Additionally,
the tracking system could possibly be obviated for simple or small
projects 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 info
in a single place (the source code) than various other documents,
likely getting duplicated or forgotten about. The completed
codetags can be sent off to the `DONE File`_, or to the bit
bucket.

----

:Objection: Codetags (and allcomments) get out of date.

:Defense: Not so much if other sources (externally visible
documentation) depend on their being accurate.

----

:Objection: Codetags tend to only rarely have estimated completion
dates of any sort. OK, the fields are optional, but you want to
suggest fields that actually will be widely used.

:Defense: If an item is inestimable don't bother with specifying a
date field. Using tools to display items with order and/or color
by due date and/or priority, it is easier to make estimates.
Having your roadmap be a dynamic reflection of your codetags makes
you 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. I
argue 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 beats
purity. There are not many fields to keep track of so one letter
prefixes are suitable.

----

:Objection: Synonyms should be deprecated since it is better to have a
single way to spell something.

:Defense: Many programmers prefer short mnemonic names, especially in
comments. This is why short mnemonics were chosen as the primary
names. However, others feel that an explicit spelling is less
confusing and less prone to error. There will always be two camps
on this subject. Thus synonyms (and complete, full spellings)
should remain supported.

----

:Objection: It is cruel to use [for mnemonics] opaque acronyms and
abbreviations which drop vowels; it's hard to figure these things
out. On that basis I hate: MLSTN RFCTR RFE FEETCH, NYI, FR, FTRQ,
FTR WKRD RVDBY

:Defense: Mnemonics are preferred since they are pretty easy to
remember and take up less space. If programmers didn't like
dropping vowels we would be able to fit very little code on a
line. The space is important for those who write comments that
often fit on a single line. But when using a canon everywhere it
is 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're
the only programmer. Terminating a codetag with ``<>`` is a small
chore, and in doing so you enable the use of the proposed tools.
Editor auto-completion of codetags is also useful: You can
program 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 granularity
for estimation/targeting purposes, and it is very compact. The
`ISO 8601`_ is widely understood but allows you to only specify
either a specific day (restrictive) or month (broad).

----

:Objection: I aesthetically dislike for the comment to be terminated
with <> in the empty field case.

:Defense: It is necessary to have a terminator since codetags may be
followed by non-codetag comments. Or codetags could be limited to
a single line, but that's prohibitive. I can't think of any
single-character terminator that is appropriate and significantly
better than <>. Maybe ``@`` could be a terminator, but then most
codetags will have an unnecessary @.

----

:Objection: I can't use codetags when writing HTML, or less
specifically, XML. Maybe ``@[email protected]`` would be a better than
``<fields>`` as the delimiters.

:Defense: Maybe you're right, but ``<>`` looks nicer whenever
applicable. XML/SGML could use ``@`` while more common
programming 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-text
indent-tabs-mode: nil
sentence-end-double-space: t
fill-column: 70
End:
 
Ad

Advertisements

T

Tom Anderson

Please read/comment/vote. This circulated as a pre-PEP proposal
submitted to c.l.py on August 10, but has changed quite a bit since
then. I'm reposting this since it is now "Open (under consideration)"
at <http://www.python.org/peps/pep-0350.html>.

Seems generally fine to me; i'm not the best person to comment, though,
since it's highly unlikely i'll use them.

I did notice one thing that is sort of wrong, though:

:Objection: *WorkWeek* is an obscure and uncommon time unit.

:Defense: That's true but it is a highly suitable unit of granularity
for estimation/targeting purposes, and it is very compact. The
`ISO 8601`_ is widely understood but allows you to only specify
either a specific day (restrictive) or month (broad).

Actually, ISO 8601 includes a week notation. Have a read of this:

http://www.cl.cam.ac.uk/~mgk25/iso-time.html

Which explains that you can write things like 2005-W20 to mean the 20th
week of 2005, and ISO won't send you to hell for it.

tom
 
P

Paul Rubin

I'm opposed to pretty much every proposal of this sort. If you want
to propose adding a feature to the language, add it in a way that the
compiler can know about it and notice when it's not used correctly.
Mere conventions that are not checked by the compiler are just more
stuff for people to remember. That doesn't say they're always useless
but in general they should not be the subject of PEP's.
 
N

Neil Hodgson

Paul Rubin:
Mere conventions that are not checked by the compiler are just more
stuff for people to remember. That doesn't say they're always useless
but in general they should not be the subject of PEP's.

The PEP system allows for the documentation of a convention as an
"Informational PEP". Documenting conventions is useful. If you don't
want conventions documented in PEPs then you should propose a change to
PEP 1, "PEP Guidelines".

Neil
 
G

George Sakkis

Paul Rubin said:
I'm opposed to pretty much every proposal of this sort. If you want
to propose adding a feature to the language, add it in a way that the
compiler can know about it and notice when it's not used correctly.
Mere conventions that are not checked by the compiler are just more
stuff for people to remember. That doesn't say they're always useless
but in general they should not be the subject of PEP's.

There are more than a dozen "informational PEPs" so far, or two dozens if you count the meta-PEPs as
well (http://www.python.org/peps/). This PEP states upfront that it is informational, so I don't see
the problem, unless are you suggesting a (meta-)PEP against informational PEPs in general :)

George
 
P

Paul Rubin

Neil Hodgson said:
The PEP system allows for the documentation of a convention as an
"Informational PEP". Documenting conventions is useful.

Where there are conventions, they should be documented. I'm in favor
of fewer conventions. If the preferred method of doing something is
consistent enough that it can be codified as a convention in a PEP, it
should be implemented in the compiler, so it becomes a language
feature, not a convention.
 
Ad

Advertisements

T

Tony Meyer

If the preferred method of doing something is
consistent enough that it can be codified as a convention in a PEP, it
should be implemented in the compiler, so it becomes a language
feature, not a convention.

Does this mean that you think that PEP 8 (Python Code Style Guide)
should be enforced by the compiler? So that (e.g) lines that are too
long just don't compile?

I really doubt you'll find much agreement for this (the compiler
should enforce it) position. The 'fewer conventions are better'
position might enjoy more support, but doesn't strike me as
particularly Pythonic (e.g. compare whitespace in Python and C).

=Tony.Meyer
 
P

Paul Rubin

Tony Meyer said:
Does this mean that you think that PEP 8 (Python Code Style Guide)
should be enforced by the compiler? So that (e.g) lines that are too
long just don't compile?

I'd be ok with compiler warning messages from lines that are too long.
I think it's appropriate to have such messages, if someone took the
trouble to specify a maximum preferred line length in the PEP. There
could be a compile time flag and/or some kind of code pragma to turn
off the warnings.
I really doubt you'll find much agreement for this (the compiler
should enforce it) position. The 'fewer conventions are better'
position might enjoy more support, but doesn't strike me as
particularly Pythonic (e.g. compare whitespace in Python and C).

It's ok if the enforcement isn't strict.
 
T

Terry Hancock

It's ok if the enforcement isn't strict.

In this case, of course, it wouldn't be the compiler, but rather
automatic documentation tools that enforce the convention (i.e.
they will choke and/or not generate correct documentation if the
convention is not followed. The PEP specifically mentions a
validating application (check that codetags are correct).

Nevertheless, enforcement does occur. This is the same situation
as with docstring conventions (fields in epydoc for example, or
using restructured text). By having a PEP convention for this
sort of thing, it becomes easier for such applications to be
written.

Doesn't that qualify as "non-strict enforcement"?
 
B

Bengt Richter

Please read/comment/vote. This circulated as a pre-PEP proposal
submitted to c.l.py on August 10, but has changed quite a bit since
then. I'm reposting this since it is now "Open (under consideration)"
at <http://www.python.org/peps/pep-0350.html>.

Thanks!
Generally, I like this (I've even rambled on the subject myself before ;-)
But I don't think DONE is a "synonym" for "TBD" or "FIXME" etc.

Some quick reactions: (in case I don't get to detailed comments ;-)

1) IMO DONE (or a well-chosen alternative) should be reserved as a tag that
you insert *after* a TODO-type code tag, and should NOT replace the TODO.
Cleaning TODO/DONE pairs out of a source is a good job for a tool, which can be
given an optional name for a project log file or DONE file etc. or take it from
an environment variable or other config mechanism. This could run as a cron job, to
clean and log, and notify etc. IOW, no error-prone manual DONE file stuff.

2) In general, I think it might be good to meet Paul Rubin half way re convention
vs syntax, but I don't think code tagging should be part of the language syntax
per se. (-*- cookies -*- really are defacto source syntax that snuck in by disguise IMO)
So perhaps a python command line option could invoke an "official" tool,
with some more options passed to it to do various checking or extracting etc.

<BF>
3) Since a source containing code tags is usually the source for a module,
a python expression with implicit scope of this module is a precise way of
referring to some elements, e.g.,

# TODO: clean up uses of magic $MyClass.MAGIC <c:magic> tool can know MyClass.MAGIC is valid expr

or <c:$MyClass.MAGIC...> ?

</BF>

4) Why can't a codetag be on the same line as code? What's wrong with
assert something, message # ???: Really always so? <>

Is it just to make tag lines python parser independent easily? To be purist, you still
have to deal with
s = """
# FIXME: I'm embedded in a string that needs the python parser to exclude <>
"""
or make conventional rule against it.

5) Sometimes time of day can be handy, so maybe <2005-09-26 12:34:56> could be recognized?

6) Maybe some way of bracketing a section of code explicitly, e.g.,

# FIXME: rework everything in this section <sect:xxx>
def foo(): pass
class Bar:
"""and so forth"""
# ...: <sect:xxx>

7) A way of appending an incremental progress line to an existing code tag line, e.g.,

# FIXME: This will take a while: rework foo and bar <WHO 2005-09-25>
# ...: test_foo for new foo works! <WHO 2005-09-26 01:23:45-0700>
# ...: vacation <WHO 2005-10-01 d:2005-10-08>

Later a tool can strip this out to the devlog.txt or DONE file, when the tool
sees an added progress line like
# ---: woohoo, completed ;-) <WHO 2005-10-11 04:56:12>

My preliminary .02USD for now ;-)

Regards,
Bengt Richter
 
P

Paul Rubin

2) In general, I think it might be good to meet Paul Rubin half way
re convention vs syntax, but I don't think code tagging should be
part of the language syntax per se. (-*- cookies -*- really are
defacto source syntax that snuck in by disguise IMO) So perhaps a
python command line option could invoke an "official" tool, with
some more options passed to it to do various checking or extracting etc.

I think there should be a single tool that knows about as many of
these conventions as possible and warns about misuse, not a bunch of
different tools. If there are a bunch of different tools, then
knowing which tools to use is yet another convention. Conventions are
un-Pythonic IMO, since one of the goals of Python is that the
knowledge you need is supposed to be right there, not something you
have to absorb through a lot of different lore and PEP's. Java has
some of the same disease, and I dislike Javadoc for about the same
reason.

Maybe the checking functions don't really belong in the
compiler/interpreter. PyChecker might be a good home for them, if
it's made part of the distro. There could be an interpreter flag to
invoke PyChecker automatically.
 
Ad

Advertisements

A

Alexandre Fayolle

Le 27-09-2005 said:
Maybe the checking functions don't really belong in the
compiler/interpreter. PyChecker might be a good home for them, if
it's made part of the distro. There could be an interpreter flag to
invoke PyChecker automatically.

Just to make a quick note that pylint [1] already has some limited
support for this, though it was developed independently from this PEP.
We will most probably add more complete support for codetags based on this
PEP in a future release of pylint.

[1] http://www.logilab.org/projects/pylint/
 
T

Terry Hancock

2) In general, I think it might be good to meet Paul Rubin half way
re convention vs syntax, but I don't think code tagging should be
part of the language syntax per se. (-*- cookies -*- really are
defacto source syntax that snuck in by disguise IMO) So perhaps a
python command line option could invoke an "official" tool, with
some more options passed to it to do various checking or extracting etc.

I think there should be a single tool that knows about as many of
these conventions as possible and warns about misuse, not a bunch of
different tools. If there are a bunch of different tools, then
knowing which tools to use is yet another convention.
[...]
Maybe the checking functions don't really belong in the
compiler/interpreter. PyChecker might be a good home for them, if
it's made part of the distro. There could be an interpreter flag to
invoke PyChecker automatically.

But that's precisely why it would be valuable to have a PEP -- a
central catalog of such conventions makes it possible for checking
software to be consistent. If PyChecker were going to check for such
things, it would do so only because a standard convention had been
established.
 
T

Tom Anderson

5) Sometimes time of day can be handy, so maybe <2005-09-26 12:34:56>
could be recognized?

ISO 8601 suggests writing date-and-times like 2005-09-26T12:34:56 - using
a T as the separator between date and time. I don't really like the look
of it, but it is a standard, so i'd suggest using it.

Bear in mind that if you don't, a black-helicopter-load of blue-helmeted
goons to come and apply the rubber hose argument to you.

tom
 
P

Paul Rubin

Terry Hancock said:
But that's precisely why it would be valuable to have a PEP -- a
central catalog of such conventions makes it possible for checking
software to be consistent. If PyChecker were going to check for such
things, it would do so only because a standard convention had been
established.

I'm saying such a PEP should not be approved unless there's already an
implementation (e.g. PyChecker patch). If the PEP is then approved,
the patch should be merged into the official PyChecker source.
 
B

Bengt Richter

ISO 8601 suggests writing date-and-times like 2005-09-26T12:34:56 - using
a T as the separator between date and time. I don't really like the look
of it, but it is a standard, so i'd suggest using it.
I knew of the ISO standard, but I don't really like the "T" connector either.
Why couldn't they have used underscore or + ? Oh well. I guess you are right though.
Bear in mind that if you don't, a black-helicopter-load of blue-helmeted
goons to come and apply the rubber hose argument to you.
Nah, ISO 8601 is not a DRM standard.

Regards,
Bengt Richter
 
Ad

Advertisements

B

Bruno Widmann

:Objection: I aesthetically dislike for the comment to be terminated
with <> in the empty field case.

:Defense: It is necessary to have a terminator since codetags may be
followed by non-codetag comments. Or codetags could be limited to
a single line, but that's prohibitive. I can't think of any
single-character terminator that is appropriate and significantly
better than <>. Maybe ``@`` could be a terminator, but then most
codetags will have an unnecessary @.

----

What about allowing a blank line between codetag and following
comment as valid terminator of codetag?

ie:
# NOTE: see spec xyz for Transport Protocol description

# how many times to retry open of a recordset
DB_OPEN_RETRYS = 3


Also if the codetag is immediatly followed by code,
all the commentlines from start of the tag to
the beginning of code could be considered part of
the codetag.

# TODO: catch possible exception here
# (in case someone deletes file)
f = open("data")
 
R

Ron Adam

Micah said:
Please read/comment/vote. This circulated as a pre-PEP proposal
submitted to c.l.py on August 10, but has changed quite a bit since
then. I'm reposting this since it is now "Open (under consideration)"
at <http://www.python.org/peps/pep-0350.html>.

Thanks!

How about an approach similar to mark up language using block comments?
It would require adding syntax to Python, but might be worth it.

# Current comments would stay the same.
#
# These won't change.
# Even if they are on a line by them selves or
# in a sequence of lines.


Possible multi-line comment with optional label.

##[label]: comment text :##


Examples:

##: an in line comment with no label :##

##:
A multi-line
comment with no label.

##:
The ##: and :## make it possible.
to nest comments.

Nesting makes it easier to comment out
sections of code without the side effects
that occur when using triple quotes.
:##
:##


## TODO:
A comment with a label.

I need to do something here.
JANE, 9/28/05
:##


## FIX ME:
Nested comments with labels.

## JOE:
I noticed if this gets stuck in a loop here.
## date: 9/25/05 :## :##
## JOHN:
I fixed it.
## date: 9/28/05 :## :##
:##


## INFO:
#
# Existing comments
# wrapped in a labeled
# block comment.
#
:##


The markup form might make it easy to read labeled comments into a
dictionary where the labels become the keys. Then special "<field>"
definitions wouldn't be needed.

Cheers,
Ron
 
?

=?iso-8859-1?Q?Fran=E7ois?= Pinard

[Tom Anderson]
ISO 8601 suggests writing date-and-times like 2005-09-26T12:34:56 -
using a T as the separator between date and time. I don't really like
the look of it, but it is a standard, so i'd suggest using it.

ISO 8601 suggests a few alternate writings, and the ``T`` you mention is
for only one of them, meant for those cases where embedded spaces are
not acceptable. Other ISO 8601 writings accept embedded spaces, and
this is how ISO 8601 is generally used by people, so far that I can see.
 
Ad

Advertisements

B

Bengt Richter

[Tom Anderson]
ISO 8601 suggests writing date-and-times like 2005-09-26T12:34:56 -
using a T as the separator between date and time. I don't really like
the look of it, but it is a standard, so i'd suggest using it.

ISO 8601 suggests a few alternate writings, and the ``T`` you mention is
for only one of them, meant for those cases where embedded spaces are
not acceptable. Other ISO 8601 writings accept embedded spaces, and
this is how ISO 8601 is generally used by people, so far that I can see.
The most detailed discussion I could find was
http://hydracen.com/dx/iso8601.htm
(BTW, IMO the practice of charging for standards documents (as the ISO
and IEEE etc do) in hard copy form is understandable, but charging for
..pdf versions is perversely contrary to the purpose of wide dissemination
necessary for wide adoption. IOW, IMO they ought to think of another way to
get funded).

Anyway, the 'T' looks to me to be optional by mutual agreement between
particular information exchangers, but otherwise required?

Regards,
Bengt Richter
 
Ad

Advertisements


Ask a Question

Want to reply to this thread or ask your own question?

You'll need to choose a username for the site, which only take a couple of moments. After that, you can post your question and our members will help you out.

Ask a Question

Top