[Python-Dev] PEP 350: Codetags

[Phillip J. Eby]

At 03:35 PM 9/26/2005 -0700, Micah Elliott wrote:
>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>.

This seems a little weird to me.  On the one hand, seems like a cool idea 
if you aren't using Eclipse or another IDE that tracks this stuff, but 
still need some kind of tracking system.  But, if that is the case, the 
notation seems a little bit overkill, especially with respect to tracking 
who's responsible - i.e., just you.

If you have a team that can agree to use the tools, I suppose it might be 
useful, but then I wonder, why not use something like Trac?

Finally, I think there should be something besides just a comment to 
distinguish these things; like starting with a symbol (e.g. # !FIXME), so 
that that documentation extraction tools can distinguish code tags from 
other documentation that just happens to start with a CAPITALIZED word.

Overall, I'm kind of -0.5.  It seems like a spec in search of an 
application.  The Motivation is sorely lacking - it reads like, "hey, it's 
optional and you can do stuff", where the stuff you can do is deferred to a 
later section, and is mostly stuff that could easily be done in other 
ways.  For example, FIT-style acceptance test documents, or Python doctest 
files go a long way towards documenting stories in association with tests, 
and they don't require you to cram things into comments.  (And because 
they're executable tests, they get kept up-to-date.)  Tracking bugfixes 
with code history is handled nicely by tools like Trac.  There are lots of 
Python documentation tools already.  And so on.  Really, it reads to me 
like you came up with the features to sell the format, instead of designing 
the format to implement specific features.

My suggestion: implement some tools, use them for a while, and come back 
with more focused use cases to show why only this format can work, and why 
the Python core developers should therefore use it.  I'm not saying that 
you can't have an informational PEP unless it should be used in the stdlib, 
mind you.  Just pointing out that if you can't convince the core developers 
it's useful, I'm thinking you'll have a hard time convincing the community 
at large to actually use it.  You need to actually have a better mousetrap 
to present before you ask people to move their cheese.  :)