PEP 350: Codetags
bokr at oz.net
Tue Sep 27 09:45:07 CEST 2005
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)"
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.
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...> ?
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
"""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 ;-)
More information about the Python-list