[Python-Dev] PEP 350: Codetags
Phillip J. Eby
pje at telecommunity.com
Tue Sep 27 19:17:16 CEST 2005
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)"
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. :)
More information about the Python-Dev