PEP 350: Codetags

[Terry Reedy]

"Micah Elliott" <mde at micah.elliott.name> [CCed] wrote in message 
[news:20050926223521.GE10940 at kitchen.client.attbi.com...

The nice thing about this is that I can use whatever part (or whatever 
version) I want regardless of whether it becomes a standard library style 
recommendation.  I would prefer tags that are short and pronouncable.  I 
think I would generally give preference to verbs over nouns when the tag 
means 'act'.  I think the tools should be able to handle local additions to 
the list since there will never be universal agreement to a reasonable size 
list.

> ``TODO (MILESTONE, MLSTN, DONE, YAGNI, TBD, TOBEDONE)``
>   *To do*: Informal tasks/features that are pending completion.

Some of the 'synonyms' don't look like synonyms to me.
I prefer the shorter verb DO.  The TO adds nothing.
For a particular project with lots of optional additions, I may use the 
more specific ADD.  DO could mean to do literally anything.

> ``FIXME (XXX, DEBUG, BROKEN, REFACTOR, REFACT, RFCTR, OOPS, SMELL, 
> NEEDSWORK, INSPECT)``
>   *Fix me*: Areas of problematic or ugly code needing refactoring or
>   cleanup.

FIX is shorter and more competitive with XXX.  In context, the addition of 
ME is meaningless.  Leave it off.  (Or write tools that let me ;-).
FIX corresponds to NOFIX and variants.
What is missing is a convention as to whether the code to be fixed (the ME) 
is above or below the note.

> ``GLOSS (GLOSSARY)``
>   *Glossary*: Definitions for project glossary.

DEF for define or definition (for glossary)

> ``TODOC (DOCDO, DODOC, NEEDSDOC, EXPLAIN, DOCUMENT)``
>   *Needs Documentation*: Areas of code that still need to be
>   documented.

DOC for document this.  TO or DO add no meaning.

> DONE File
> ---------
> It may sound burdensome to have to delete codetag lines every time one
> gets completed.  But in practice it is quite easy to setup a Vim or
> Emacs mapping to auto-record a codetag deletion in this format (sans
> the commentary).

Not everyone uses Vim or Emacs.  Would it be as easy to setup IDLE or 
PythonWin to do the same?  Suggestion: add an x:comment field, to mean 
'this tag  is ready to be deleted, perhaps to be transferred to a done file 
first'.
-----

I generally agree with your objection defenses except possible this one.

> :Objection: I can't use codetags when writing HTML, or less
>    specifically, XML.  Maybe ``@fields@`` would be a better than
>    ``<fields>`` as the delimiters.
>
> :Defense: Maybe you're right, but ``<>`` looks nicer whenever
>    applicable.  XML/SGML could use ``@`` while more common
>    programming languages stick to ``<>``.

XML is not going change.  On the other hand, < and > routinely occur in 
Python code already.  Don't they already have to be escaped to embed Python 
in HT/XML?

Terry J. Reedy