PEP 350: Codetags

[Bengt Richter]

On Mon, 26 Sep 2005 15:35:21 -0700, Micah Elliott <mde at micah.elliott.name> 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>.
>
>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