PEP 350
Please add comments/feedback to the bottom of this wiki document using WikiRestructuredText.
This document now lives as an "Open PEP" under consideration at http://www.python.org/peps/pep-0350.html
But please continue to add comments here, or post to comp.lang.py.
-- MicahElliott
Comments
There has been some discussion on comp.lang.py (subject: "Pre-PEP Proposal: Codetags").
-- MicahElliott
I informed a previous c2.com discussion <http://c2.com/cgi/wiki?FixmeComment> about this. Comments might show up here or there. -- MicahElliott
I like it; I ask that there be a separate TODO called "DOC".
I used to use "TODO" wherever I wanted to remind myself to write a doc-string before. But then I couldn't find the ''real'' to-do's to do (those requiring programming work.) So I settled on using "DOC" for "to be documented," and have lived peacefully since then. (Documentation happens in a later pass.)
That said, if you have some other solution for me: As long as you're making the tools for this, just let me know what it is, and I won't complain.
Nice idea. This is now provided as "TODOC". --MicahElliott
Perhaps there could be a syntax for which lines the tag applies to, so if you have a HACK <10> tag, you know you should rewrite the following n lines.
Good idea; that crossed my mind too. My concern is that as soon as the 10 lines shrinks or grows, the codetag is out of date. I would think it could be a custom field, say "Context (C)". --MicahElliott
I would also use named variables for the parameters in the <>.
Done. Most tags are now prefixed with 1-character labels. --MicahElliott
Finally (just rambling) you could write a hooks in python for each tag type that would be automatically passed the text and the parameters.
You left out "wontfix", which is somewhat controversial, but indispensible in some circumstances, such as: it's agreed that something is a bug, but it won't be fixed because the entire module is going to be rewritten anyway, which will make the issue moot.
Despite Sun's attempt to impose a standard on FIXME vs XXX, there's already too many decades of chaos on that topic, and too many millions of developers who won't be influenced by Sun, so I think the two should be regarded as synonyms -- and for XXX to be excluded from the standard list, since "FIXME" is completely mnemonic.
It is cruel to use opaque acronyms and abbreviations which drop vowels; it's hard to figure these things out. On that basis I hate: MLSTN RFCTR RFE FEETCH, NYI, FR, FTRQ, FTR WKRD RVDBY
I aesthetically dislike for the comment to be terminated with <> in the empty field case, and I'm not so sure I like <wNN pN DRM> as the terminator in the non-empty situation, either. The terminator should probably just be different than the field markers.
The fields that you propose seem fairly arbitrary. Workweek (wNN) for instance an uncommon time unit, and furthermore, TODO/FIXME comments tend to only rarely have estimated completion dates of any sort. Ok, the fields are optional, but you want to suggest fields that actually will be widely used.
The field for the initials of owner: should be more than just initials. Initials are common, but so are full names, ad hoc abbreviations ("DougM" and "DougJ" both on same project).
The priority level: As soon as I see priority, I wonder where "severity" went. The next thing I wonder is what the scale is; 0..9? Is 0 low priority or high? Then I also remember that people are always confusing priority and severity, and that some people are really bad at judging priority and/or severity. Some people will always mark every bug as a showstopper -- which implies that there must always be a name associated with priorities and severities, to know whether to take them seriously or not.
Which brings up the overall issue that some of these things will be automatically fed into bug trackers and PIM ToDoLists? etc, so as long as you're including a few things related to bug trackers, you may as well include all of them (as with the "severity" example above), by looking at several bug trackers and seeing which kind of keywords they support.
In fact, I think that in an ideal environment, each and every single such tag would be automatically forwarded to the appropriate piece of software/person. Some people argue against FixmeComments? because they should be in bug trackers or in project planners; I disagree (who's going to forbid me from commenting my code?), but setting things up so that the tags can be auto-forwarded when desired gives the best of both worlds.
It also then provides a framework for which tags should exist and which attributes they should have. The tags that don't seem appropriate to forward to any kind of tracking software might be candidates for deletion from the standard list. Or maybe they are a signal that we should invent a new kind of tracking software. ThingsThatFallThroughTheCracks?-Catcher version 2.1 :-)
-- DougMerritt
Thanks for the great feedback, Doug. Much of this has been addressed and incorporated into a recent version of the PEP. --MicahElliott
Although it's not 100% Python-specific, I see no reason to disallow the PEP. Indeed, I think it's a good idea.
<Next comment here>
