[Zope3-dev] New XXX policy (and TODO and BBB)

[Jim Fulton]

As mentioned in a an earlier message, we've been making far too
much use of XXX comments.  Going forward, I propose the following
policy for XXX comments:

- XXX comments should only be used during development to note
   things that need to be taken care of before a final (trunk) commit.

   One should not expect to see XXXs in released software.
   (Even though Zope X3.0 will have hundred's of XXXs. :( )

- It should be extremely rare to check in an XXX on a trunk.  If an XXX
   is checked in on a trunk:

   o The intention and expectation will be that someone will resolve the XXX
     before someone releases the code.

   o The XXX must fully describe an issue, so that someone else can read the
     comment and know what it's about.

XXX shall not be used to record new features, non-critical optimization,
design changes, etc. If you want to record things like that, use TODO comments
instead.  People making a release shouldn't care about TODOs, but they ought
to be annoyed to find XXXs.

Finally, when we add code for backward compatability, please use a BBB
comment with a date.

   # BBB 2004-7-8, bried description

Anyone want to add a page to the style guide?

Jim

-- 
Jim Fulton           mailto:jim at zope.com       Python Powered!
CTO                  (540) 361-1714            http://www.python.org
Zope Corporation     http://www.zope.com       http://www.zope.org