Re: [Python-Dev] PEP 350: Codetags
At 09:10 AM 9/28/2005 -0700, Micah Elliott wrote: 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. My point about the lack of motivation was that there was little reason shown why this should be a PEP instead of either: 1. Documentation for a specific tool, or group of tools 2. A specific project's process documentation Are you proposing that this format be used by the Python developers for Python itself? A process spec like this seems orthogonal to Python-the-language. To put it another way, this seems like writing a PEP on how to do eXtreme Programming, or perhaps a PEP on how the blogging trackback protocol works. Certainly you might implement those things using Python, but the spec itself seems entirely orthogonal to Python. I don't really see why it's a PEP, as opposed to just a published spec on your own website, unless you intend for say, the Python stdlib to conform to it. -- http://mail.python.org/mailman/listinfo/python-list
Re: [Python-Dev] PEP 350: Codetags
On 9/29/05, Phillip J. Eby [EMAIL PROTECTED] wrote: My point about the lack of motivation was that there was little reason shown why this should be a PEP instead of either: 1. Documentation for a specific tool, or group of tools 2. A specific project's process documentation That's what I feel as well. I hadn't commented on the PEP as I had simply intended to ignore it totally in my own projects... Paul. -- http://mail.python.org/mailman/listinfo/python-list
Re: [Python-Dev] PEP 350: Codetags
Micah Elliott [EMAIL PROTECTED] wrote: 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. Defining a spec for code tags doesn't mean that people will start using them. Why? Because it is a documentation spec. From my experience, documentation specs are only adhered to by the organizations (companies, groups, etc.) which the code is produced by and for, and they generally define the code specs for their organization. Further, even if it becomes a spec, it doesn't guarantee implementation in Python editors (for which you are shooting for). Take a wander through current implementations of code tags in various editors to get a feel for what they support. I've read various posts about what code tags could support, but not what editors which implement code tags and/or its variants actually currently support; which is a better indication of what people want than an informal survey via email of python-dev, python-list, and/or the PEP submission process. - Josiah -- http://mail.python.org/mailman/listinfo/python-list
Re: [Python-Dev] PEP 350: Codetags
At 03:35 PM 9/26/2005 -0700, Micah Elliott 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. This seems a little weird to me. On the one hand, seems like a cool idea if you aren't using Eclipse or another IDE that tracks this stuff, but still need some kind of tracking system. But, if that is the case, the notation seems a little bit overkill, especially with respect to tracking who's responsible - i.e., just you. If you have a team that can agree to use the tools, I suppose it might be useful, but then I wonder, why not use something like Trac? Finally, I think there should be something besides just a comment to distinguish these things; like starting with a symbol (e.g. # !FIXME), so that that documentation extraction tools can distinguish code tags from other documentation that just happens to start with a CAPITALIZED word. Overall, I'm kind of -0.5. It seems like a spec in search of an application. The Motivation is sorely lacking - it reads like, hey, it's optional and you can do stuff, where the stuff you can do is deferred to a later section, and is mostly stuff that could easily be done in other ways. For example, FIT-style acceptance test documents, or Python doctest files go a long way towards documenting stories in association with tests, and they don't require you to cram things into comments. (And because they're executable tests, they get kept up-to-date.) Tracking bugfixes with code history is handled nicely by tools like Trac. There are lots of Python documentation tools already. And so on. Really, it reads to me like you came up with the features to sell the format, instead of designing the format to implement specific features. My suggestion: implement some tools, use them for a while, and come back with more focused use cases to show why only this format can work, and why the Python core developers should therefore use it. I'm not saying that you can't have an informational PEP unless it should be used in the stdlib, mind you. Just pointing out that if you can't convince the core developers it's useful, I'm thinking you'll have a hard time convincing the community at large to actually use it. You need to actually have a better mousetrap to present before you ask people to move their cheese. :) -- http://mail.python.org/mailman/listinfo/python-list
Re: [Python-Dev] PEP 350: Codetags
On 9/27/05, Phillip J. Eby [EMAIL PROTECTED] wrote: At 03:35 PM 9/26/2005 -0700, Micah Elliott 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. My suggestion: implement some tools, use them for a while, and come back with more focused use cases to show why only this format can work, and why the Python core developers should therefore use it. I'm not saying that you can't have an informational PEP unless it should be used in the stdlib, mind you. Just pointing out that if you can't convince the core developers it's useful, I'm thinking you'll have a hard time convincing the community at large to actually use it. You need to actually have a better mousetrap to present before you ask people to move their cheese. :) +1 I agree with PJE almost entirely. Peace Bill Mill bill.mill at gmail.com -- http://mail.python.org/mailman/listinfo/python-list
Re: [Python-Dev] PEP 350: Codetags
Phillip J. Eby [EMAIL PROTECTED] wrote: At 03:35 PM 9/26/2005 -0700, Micah Elliott 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. This seems a little weird to me. On the one hand, seems like a cool idea if you aren't using Eclipse or another IDE that tracks this stuff, but still need some kind of tracking system. But, if that is the case, the notation seems a little bit overkill, especially with respect to tracking who's responsible - i.e., just you. There are various Python editors which have had support for a similar style of tags for quite a while. Some allow #anything: comment, others allow # alphanumeric and spaces : comment, even others allow more or less. Some even count exclamation points as an indicator of severity. Personally, though I use tags in some of the code I write, and though the editor I use (and wrote) supports tags, I'm of the opinion that an unofficial spec is sufficient. See koders.com and search for 'fixme' to see some common variants. - Josiah -- http://mail.python.org/mailman/listinfo/python-list
Re: [Python-Dev] PEP 350: Codetags
At 03:35 PM 9/26/2005 -0700, Micah Elliott 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.
-1
Personally I do use code tags in my code, but not from this standardised
set, nor would I wish to. I tend to use:
TODO
SMELL
STINK
STENCH
VOMIT
... depending on context. Sometimes they might relate to third party
libraries which the code is a workaround for, and hence can't really be
fixed beyond the SMELL stage. STENCH and VOMIT I tend to use as my priority
mechanism for TODOs. Generally only used if the code can't be fixed or
deleted when the decision to tag the code as STENCH or VOMIT. The last 3
are only very, very rarely used. (I'll also only tend to tag my own code
that way since they can be taken the wrong way by people :)
An example of how I use SMELL (a long lived comment on the implementation
that is wrong, but exists for a reason):
#
# SMELL : Periodically check if this is still needed or not.
#
# OVERLAY_FUDGE_OFFSET_FACTOR is the result of experimentally
# trying to get SDL_Overlay/pygame.Overlay to work with Xorg/fbdev
# based displays on linux. If the overlay is precisely the right
# size and shape for the data, it can't be displayed right.
# The value must be even, and preferably small. Odd values
# result in the picture being sheared/slanted.
#
# This problem rears itself when the following version numbers are aligned:
#SDL : 1.2.8
#pygame : Anything up to/including 1.7.1prerelease
#xorg : 6.8.2
#Linux (for fbdev) : 2.6.11.4
It sits there as a clear warning/comment for the next developer. This kind
of comment doesn't really map to the contents of the PEP in any sensible
way, and yet uses the SMELL code tag as a clear warning.
Having a standard set of tags /within/ a project is good. Recommending
a single set across all projects seems un-enforceable, and hence loses
the stated benefits of uniformity. (Kinda the python equivalent of the
C-style-language flame wars of the right place to place braces { } in
your code)
If the intent is to have an aim for a standard set of tags within the
/standard library/, that seems a more reasonable goal, but have a big
set of tags is a problem there, since no one will ever really remember
a big list of random tags (or is that just me?).
I also think the fields idea is a big mistake.
As a code standard for a *particular* project it looks fine, but not for
all.
Michael.
--
http://mail.python.org/mailman/listinfo/python-list
