PEP 350: Codetags

[Micah Elliott]

Thanks to all who have read and/or provided feedback.  There have been
some great ideas and admonitions that hadn't crossed my mind.  I'll
paraphrase some of the responses for the sake of brevity; I don't mean
to misquote anyone.

Tom> ISO 8601 includes a week notation.

That's great.  Thanks for pointing it out; seems like it should be the
preferred week format.  I might also want to allow a simple W42 (say)
since it's so much shorter, and I'll consider myself generally in
trouble if I wrap around on the year for due items.

Terry> Shorter forms such as DO, FIX, DEF, DOC, etc. are better.

I like the short proposals, so I'll add, and possibly even canonize
them.  My proposed canons were based on popular use and also my taste.
I had originally wanted to state that only the canonical forms would
be supported and use of the synonyms should be deprecated.  That would
have simplified things a bit (human and tool parsing).  But based on
people's ideas about what is canonical, that would never have flown.
Instead, it seems useful to just list everything that's ever been used
as long as it *fits one of the categories*.  And the canon is mostly
arbitrary/unnecessary; we'd never settle that peacefully anyway.  The
main point is that official categorization enables construction of
productivity tools.

Terry> IDEXXX isn't vim/emacs.  Offer an x:"comment" field for a
Terry> completed item.

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

I wish we could rely on everyone to have/use cron.  These are both
great ideas.  I'd like to allow/have both.

Bengt> 7) A way of appending an incremental progress line to an existing code
Bengt> tag line, e.g.,
Bengt> # FIXME: This will take a while: rework foo and bar <WHO 2005-09-25>
Bengt> # ...: test_foo for new foo works! <WHO 2005-09-26 01:23:45-0700>
Bengt> # ...: vacation <WHO 2005-10-01 d:2005-10-08>

Status updates?  Nice!!  Great syntax too.

Bengt> time, embedded in strings, scope, no DONE, same line as code...

Your pennies are gold!  Thanks!

Another thing that came to mind recently:  As with docstrings, the
first sentence of a multiline codetags should be a meaningful summary.
So for multiline codetags I'll suggest that the fist line be something
that could show up in say a manpage or a BUGFIX file.

Terry> Terminator <> is evil.  Whitespace is good.

Bruno> Or if the codetag is immediately followed by code it's
Bruno> terminated.

Yes, I'd actually forgotten that it is also not-equal!  And I agree
that \n\n (or code) is a good terminator.  I had been in the practice
of putting some TODOs together near the tops of my modules, but a
white line between would probably look cleaner anyway.

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

That might be necessary.  But if the extraction tools are aware of all
official codetags, then it becomes less important.  It might even be
useful for lint tools to comment when seeing a line that begins with
say "# FOO:" but isn't a codetag.  Most such uses probably fall under
one of the proposed categories anyway.

pythondev> It has always been my choice to *only* use XXX. I hope there
pythondev> aren't any developers contributing to the Python core who
pythondev> use any others?

$ csrcs=$(find ~/archive/Python-2.4.1 -name *.c)
$ for tag in '!!!' '\?\?\?' XXX WARN CAUTION \
    TBD FIXME TODO BUG HACK Note NOTE RFE IMPORTANT; do
      echo -n "$tag: "; egrep"\b$tag" $csrcs |wc -l
  done
!!!: ~1
\?\?\?: ~12  [most of these part of XXXs]
XXX: 365
WARN: ~4
CAUTION: 16
TBD: ~2
FIXME: 12
TODO: 12
BUG: 0
HACK: 0
Note: ~306
NOTE: ~9
RFE: 0
IMPORTANT: ~6  [some overlap with NOTEs]

I subtracted most of the false positives but I think the model is
being implicitly used to a small degree already.  It's just hard to
know that they're in the code.  I'm impressed there are so few in 365
KLOC.  I also notice some WHO: initials, as well as Hmmm:, bad:,
Reference:, Obscure:, NB:, Bah:, and others.

pythondev> I honestly don't see much of a point for
pythondev> distinguishing different types; these are for humans to read
pythondev> and review, and different tags just makes it harder to grep.

Yes, they are hard to grep!  And so are XXXs if multi-line.  You'd
have to do something like "$EDITOR `grep -l XXX $csrcs`" to really
grok them.  That's why a different tool is needed for inspection.
Even if the codetag paradigm is despised for a given project,
something (pychecker/pylint) needs to do a proper scan to
address/remove/alert them.  I won't argue that the interpreter should
adopt codetags, but it would at least benefit from lint recognition.

Phillip> You still need a tracking system.

Agreed, for most projects, and I think Trac is great.  But some might
want to use codetags as a way to track anything that is not a
full-blown bug.  And how many times have you seen small projects that
say, "We don't have a bug tracker yet.  Please just send bugs to
<bugs at anothersmallproject.org>"?

Josiah> Some even count exclamation points as an indicator of severity.

Michael> I prefer TODO SMELL STINK STENCH VOMIT to indicate TODO priority.

These seem useful.  But I personally prefer a single TODO with a
numeric priority, and I feel that the p: field is the simplest way to
get that (easier to remember numbers 0..3 than contaminations or
!-counts).  I think the example you gave could be done with a "#
FIXME: <p:2>..." and still be obvious, or even "# FIXME:
<p:Stench>...", assuming you have mapped your bletcherosity level to
numbers.  This also assumes Terry's whitespace idea is used so the
fields could show up at the front.  Note that the PEP has separated
TODO from FIXME semantics.

Josiah> an unofficial spec is sufficient.  See koders.com and search
Josiah> for 'fixme' to see some common variants.

But that's the problem -- there are already a bunch of "unofficial"
specs, which don't serve much purpose as such.  It's a cool site.  I
spent some time browsing and I do see a lot of codetags in use (many
thousands in Python code alone; I'm not sure if the number represented
strings or files).  But I'll argue that this just reinforces the need
for an *official* spec/guideline, so that the tools can do something
with them.

Paul> Such a PEP should not be approved unless there's
Paul> already an implementation (e.g. PyChecker patch)

Phillip> implement some tools, use them for a while, and come back
Phillip> with more focused use cases

Phillip> It seems like a spec in search of an application.  The
Phillip> Motivation is sorely lacking 

My two main motivations are avoiding duplication (for documentation)
and organizing tasks.  I'm presently using it on a smallish project (5
KLOC) to generate manpage sections (fed to help2man) for BUGS,
GLOSSARY, and RFE.  These should arguably be dumped to a
BUGS/BUGFIX/ChangeLog file.  I haven't yet figured out how to make
Trac or SourceForge do a nice creation of such a file, though it's
essential IMO to provide one with a source package.  BUGS files are
also non-standardized, though I've seen some pretty nice (yet wildly
different) ones, and a tool could help here.

The other current use (for me) is as a grep replacement.  The tools
(just ctdoc right now) are limited (pre-alpha) but really help me
address the right tasks in the right order.  See
<http://tracos.org/codetag/wiki/ScreenShots> for a little comparison
to grepping.  I do think that the health-o-meter is also valuable (I
see that pylint already does a nice job of this).

I agree that proof of value is necessary.  Without a spec though it
will be hard to get people to know about a convention/toolset, so it's
a bit of a chicken-egg problem -- I can't have a pep until the tools are
in use, but the tools won't be used until programmers have
means/motivation to use them, a pep.

But now that I have your feedback/ideas I (and maybe the lint folks)
can do better job of expanding flexible tools that can prove this
paradigm useful (or useless).

I will continue development on the tools and encourage anyone
interested in using a standard set of codetags for documentation and
tracking purposes to give them a try (and provide more feedback!) as
they mature.

-- 
Micah Elliott