[Checkins] SVN: zope3docs/ Clean up TODO comment documentation.

[Christian Theune]

Log message for revision 96784:
  Clean up TODO comment documentation.
  

Changed:
  _U  zope3docs/
  U   zope3docs/source/codingstyle/todocomments.rst

-=-

Property changes on: zope3docs
___________________________________________________________________
Modified: bzr:revision-info
   - timestamp: 2009-02-19 14:34:10.486000061 +0100
committer: Christian Theune <ct at gocept.com>
properties: 
	branch-nick: zope3docs.bzr

   + timestamp: 2009-02-19 14:41:27.305999994 +0100
committer: Christian Theune <ct at gocept.com>
properties: 
	branch-nick: zope3docs.bzr

Modified: bzr:file-ids
   - source/codingstyle/zcml-style.rst	96696 at 62d5b8a3-27da-0310-9561-8e5933582275:zope3docs:source%2Fcodingstyle%2Fzcml-style.rst

   + source/codingstyle/todocomments.rst	96696 at 62d5b8a3-27da-0310-9561-8e5933582275:zope3docs:source%2Fcodingstyle%2Ftodocomments.rst

Modified: bzr:revision-id:v3-single-zope3docs
   - 16 ct at gocept.com-20090219095131-k60befy2nrfx9q99
17 ct at gocept.com-20090219101837-g1g0cg0op0o8a104
18 ct at gocept.com-20090219104745-nh3531xbm8hsd2v9
19 ct at gocept.com-20090219105006-0mre3cx94v8awk9m
20 ct at gocept.com-20090219105021-qywg1ei5q6a21223
21 ct at gocept.com-20090219105034-je5udw7hy1r7xel5
22 ct at gocept.com-20090219133402-h5djqf2t1nfow9k3
23 ct at gocept.com-20090219133410-1vdvhnc62v0ix14u

   + 16 ct at gocept.com-20090219095131-k60befy2nrfx9q99
17 ct at gocept.com-20090219101837-g1g0cg0op0o8a104
18 ct at gocept.com-20090219104745-nh3531xbm8hsd2v9
19 ct at gocept.com-20090219105006-0mre3cx94v8awk9m
20 ct at gocept.com-20090219105021-qywg1ei5q6a21223
21 ct at gocept.com-20090219105034-je5udw7hy1r7xel5
22 ct at gocept.com-20090219133402-h5djqf2t1nfow9k3
23 ct at gocept.com-20090219133410-1vdvhnc62v0ix14u
24 ct at gocept.com-20090219134127-4xq75osx1qizp1lh


Modified: zope3docs/source/codingstyle/todocomments.rst
===================================================================
--- zope3docs/source/codingstyle/todocomments.rst	2009-02-19 17:28:27 UTC (rev 96783)
+++ zope3docs/source/codingstyle/todocomments.rst	2009-02-19 17:28:29 UTC (rev 96784)
@@ -1,45 +1,48 @@
-TO-DO Comments
-==============
+TODO comments
+=============
 
-  Occassionally you may need to note places in code that need to be
-  revisited later. There are three standard codes used in Python
-  comments used to designate such code:
+Occasionally you may need to note a place in a file that needs to be
+revisited later. There are three standard codes used to designate such
+places: ``XXX``, ``TODO``, and. ``BBB``
 
-  o XXX
+Depending on the type of the file, those codes should be placed
+within a comment according to the applicable syntax.
 
-  o TODO
 
-  o BBB
+XXX
+  XXX comments should only be used during development to note things
+  that need to be taken care of before a final (trunk) commit::
 
-  XXX
+    # XXX This will break if someone types `9`.
 
-    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 XXX in released software.
 
-    One should not expect to see !XXXs in released software.
+  It should be extremely rare to check in an XXX on a trunk. If an
+  XXX is checked in on a trunk:
 
-    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 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.
 
-    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.
 
-    XXX shall not be used to record new features, non-critical
-    optimization, design changes, etc.
 
-  TODO
+TODO
+  If you want to record things like new features, non-critical
+  optimizations, design changes, or other long term changes, use
+  TODO comments::
 
-    If you want to record things like new features, non-critical
-    optimizations, design changes, or other long term changes, use
-    TODO comments. People making a release shouldn't care about !TODOs, 
-    but they ought to be annoyed to find !XXXs.
+    # TODO This could go faster if we'd use a better data structure.
 
-  BBB
+  People making a release shouldn't care about TODOs, but they ought to
+  be annoyed to find XXXs.
 
-    When adding code to preserve backward compatibility, use a BBB
-    comment with a date. For example::
 
-      # BBB 2004-07-08, preserves use of 'get_foo' function
+BBB
+  When adding code to preserve backward compatibility, use a BBB
+  comment with a date. For example::
+
+    # BBB 2004-07-08, preserves use of 'get_foo' function