[Python-Dev] PEP 350: Codetags

[Michael]

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.