Pre-PEP Proposal: Codetags

[mdelliot at gmail.com]

Wow, thanks for all the quick responses!

Martin wrote:
> the PEP author is typically expected to implement the proposed
> functionality (in many cases, having a draft implementation is
> prerequisite to accepting it).

Fuzzyman wrote:
> ...you could take your proposal forward by developing a set of tools
> (e.g.  documentation tools) that use your proposal. That way people
> have a working implementation to use.

Yes, I'm working on that and should have some tools reasonably
functional within the next few months. I didn't want to commit a lot
of time to writing tools if no one showed interested in the proposed
conventions. Since no one is flaming the idea yet, I will get a
move-on. The five example tools (that have come to mind so far) which
I mentioned in the pre-pep were:

* Document Generator (glossary, roadmap, manpages, bug lists, etc.)

* Codetag History (useful for estimating, autopsy, etc.)

* Code Statistics (a project Health-O-Meter)

* Codetag Lint (aid in fixing almost-Codetags)

* Story Manager/Browser (graphical viewer for various potential
purposes)

I'd love to hear any other ideas.

Aahz and Terry wrote:
> it's also true that there are plenty of informational PEPs...
> ...It is similar in this way and complementary to reStructuredText
> Docstring Format...

Right, that's why I thought the PEP process was appropriate for this,
like it was for restructuredtext. This of course is much smaller
scale. I just want the proposal to live somewhere where I can get some
feedback.  I haven't seen much in the way of "+/-" yet, but that's
fine since Codetags are not implemented/in use yet.

amk wrote:
> If such things are deemed off-topic for PEPs, then I think we should
> have a separate set of documents for this (perhaps the suggested
> PEEPS: Python Environment Enhancement Proposals).

Sounds great. Make it a PEEP! I couldn't find anything official about
PEEPs yet :-)  I did create a link to PEEPs from the Front Page wiki.

Terry wrote:
> The OP might also look for codetag usage in Python source (I know of
> XXX)

Great idea. I tried this some months ago and this was one of the
things that justified the idea. For some cursory stats:

$ csrcs=$(find ~/archive/Python-2.4.1 -name *.c)
$ for tag in XXX FIXME TODO BUG HACK IDEA NOTE RFE; do
>   echo -n "$tag: "; grep $tag $csrcs |wc -l
> done
XXX: 376
FIXME: 11
TODO: 12
BUG: 109
HACK: 0
IDEA: 0
NOTE: 32
RFE: 0
$
$ pysrcs=$(find /usr/lib/python2.3/ -maxdepth 2 -name '*.py')
$ for tag in XXX FIXME TODO BUG HACK IDEA NOTE RFE; do
>   echo -n "$tag: "; grep $tag $pysrcs |wc -l
> done
XXX: 457
FIXME: 10
TODO: 57
BUG: 149
HACK: 0
IDEA: 0
NOTE: 50
RFE: 0

So I guess I'll now ask for ongoing feedback on the PEEP wiki site.
I'm happy to wait for that feedback while the toolsmithing gets
underway.  Maybe a PEEP process discussion is warranted for another
c.l.py thread.

--
Micah Elliott