Update codingstyle docs.

docs/codingstyle/checkin-guidelines.rst

@@ -7,16 +7,17 @@ Please be careful before a check in to make sure:
    If you want to check in partial code in order to collaborate remotely,
    do so in a branch.
 
- - All the tests pass. Running individual tests for the code you are working on is fine
-   while developing, but immediately before a check in, all tests must be run.
+ - All the tests pass. Running individual tests for the code you are
+   working on is fine while developing, but immediately before a check
+   in, all tests must be run.
 
    Build environments based on buildout usually do so by running::
 
       bin/test --all
 
- - Use 'svn status' to make sure you have added any new files to the
+ - Use 'git status' to make sure you have added any new files to the
    repository.  Alternatively you could make a fresh checkout before running
    the tests.
 
  - Please be aware of the version of Python you use. The recommended and
-   supported versions of Python vary over time (also they do so slowly).
+   supported versions of Python vary over time (although they do so slowly).

docs/codingstyle/index.rst

@@ -5,17 +5,11 @@ The coding style is intended to support a consistent code base by laying
 out rules for how to work on Zope code, for example how to structure
 files, format your source code and naming things.
 
-.. note::
-    TODO This area includes code from the original Zope 3 wiki and needs
-    gardening work.
-
 .. toctree::
     :maxdepth: 1
 
     python-style
     zcml-style
     todocomments
-
     checkin-guidelines
     writingtests
-    glossary

docs/codingstyle/python-style.rst

@@ -19,23 +19,14 @@ conventions.
 License statement, module docstring
 -----------------------------------
 
-Python files should always contain the most actual license comment at the top followed by the
-module documentation string.
-
-The docstring should contain a reference about version control status.
-The example given is valid for Subversion.
-
-.. note::
-
-   The community has decided not to continue the use of the CVS keyword
-   expansion feature, e.g., the ``$Id`` tag.  Any keywords can be removed as
-   they are found during module cleanup.
+Python files should always contain the most current license comment at
+the top followed by the module documentation string.
 
 Here is the template::
 
   ##############################################################################
   #
-  # Copyright (c) 2009 Zope Foundation and Contributors.
+  # Copyright (c) 2016 Zope Foundation and Contributors.
   # All Rights Reserved.
   #
   # This software is subject to the provisions of the Zope Public License,
@@ -51,28 +42,12 @@ Here is the template::
   Module documentation goes here.
   """
 
-.. note::
-    TODO We never finished discussing license years. When should the
-    license year be updated? Do we have to enumerate individual years or
-    is it ok to give ranges?
-
-    Guido (around 2002) pointed out the FSF's rules. Those should be
-    re-evaluated.
-
-    Efge pointed out that in the US only the first year of publication
-    needs to be given. (See http://www.loc.gov/copyright/circs/circ03.html).
-
-    This also points out that we need an understanding of when code is
-    published the first time. Can checking into a public repository can
-    count as published? The FSF seemed to understand inclusions in
-    release tarballs as publications.
-
 
 Whitespace
 ----------
 
-Trailing whitespace should not occur, nor should blank lines at the end
-of files.
+Trailing whitespace should not occur, nor should multiple blank lines
+at the end of files.
 
 
 Import statements
@@ -82,41 +57,26 @@ All imports should be at the top of the module, after the module
 docstring and/or comments, but before module globals.
 
 It is sometimes necessary to violate this to address circular import
-pronlems. If this is the case, add a comment to the import section at
+problems. If this is the case, add a comment to the import section at
 the top of the file to flag that this was done.
 
-Order your imports by simply ordering the lines as `sort` would. Don't
-create blocks of imports with additional empty lines as PEP 8 recommends.
+Refrain from using relative imports. Instead of::
 
-.. note::
-    TODO This rule has been recommended by Jim but hasn't been
-    officially established.
-
-
-Refrain from using relative imports.  Instead of::
-
-    import foo # from same package
+    import .foo  # from same package
 
 you can write::
 
-    from Zope.App.ThisPackage import foo
-
-.. note::
-    TODO Clarify, clean up wording. I think we also avoid re-imports of
-    symbols and most times prefer the ``import`` over the ``from`` form.
-
-    Relative imports should be avoided, I'm not sure about the style 
-    once we start getting real relative imports from Python.
+    from zope.package.module import foo
 
 
 Attribute and method names
 --------------------------
 
 The naming of attributes as recommended by PEP 8 is controversial. PEP 8
 prefers ``attribute_name`` over ``attributeName``. Newer code tends to
-prefer the use of underscores over camel case. However, Zope 3 has been
+prefer the use of underscores over camel case. However, Zope has been
 built originally with the latter rule and a lot of code still use this
-meme.
+scheme.
 
 Boolean-type attributes should always form a true-false-question,
 typically using "has" or "is" as prefix. Example: ``is_required`` instead
@@ -139,35 +99,16 @@ Examples::
     command()
     string()
 
-
-.. note::
-    TODO This rule needs clarification.
-
-
-Global variable names
----------------------
-
-Public global variables names are spelled with CapitalizedWords, as in
-``Folder`` or ``RoleService``.
-
-An exception is made for global non-factory functions, which are
-typically spelled with ``mixedCase``.
-
-.. note::
-    TODO This rule needs clarification. What is a global variable
-    anyway? It's not a constant AFAICT.
-
-
 Local variables
 ---------------
 
 Single-letter variable names should be avoided unless:
 
  - Their meaning is extremely obvious from the context, and
 
- - Brevity is desireable
+ - Brevity is desirable
 
-The most obviouse case for single-letter variables is for iteration
+The most obvious case for single-letter variables is for iteration
 variables.
 
 
@@ -205,19 +146,6 @@ error-prone than comparing sliced strings::
     if foo[-5:]=='.html':
         ...
 
-.. note::
-    TODO: Is this rule already PEP 8?
-
-When checking if a string is a string, keep in mind that it might be a
-unicode string too! The ``basestring`` type matches both ``str`` and
-``unicode`` objects::
-
-    if isinstance(obj, basestring):
-        ...
-
-.. note::
-    TODO Does PEP 8 talk about this already?
-
 Type checks
 -----------
 
@@ -238,12 +166,9 @@ Marker objects
 --------------
 
 Use instances of ``object`` if you need to construct marker objects (for
-example when detecting default values).  Compare them using ``is`` as
+example when detecting default values). Compare them using ``is`` as
 recommended by PEP 8.
 
-.. note::
-    TODO This was recommended by Steve Alexander but hasn't been
-    officially approved for inclusion. Clarify its status.
 
 Interfaces
 ----------
@@ -260,12 +185,5 @@ than once. Interfaces that are likely to be implemented only once, like
 ``IGlobalAdapterService``, should live in the same module as their
 implementation.
 
-.. note::
-    TODO clarify whether the single/multiple implementation rule holds.
-
-    TODO there has been discussion about whether imperative or
-    present tense is to be preferred for describing interfaces. The
-    discussion was not resolved.
-
 
 .. _`PEP 8`: http://www.python.org/dev/peps/pep-0008/

docs/codingstyle/todocomments.rst

@@ -3,7 +3,7 @@ TODO comments
 
 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``
+places: ``XXX``, ``TODO``, and ``BBB``.
 
 Depending on the type of the file, those codes should be placed
 within a comment according to the applicable syntax.
@@ -45,4 +45,4 @@ 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
+    # BBB 2016-07-08, preserves use of 'get_foo' function

docs/codingstyle/writingtests.rst

@@ -2,24 +2,18 @@ Writing tests
 =============
 
 For any module 'somepkg.somemod' there should be a corresponding
-unit test module 'somepkg.somemod.tests.testSomemod'.  Or if more than one
-set of unit tests is desired, multiple test modules of the form
-'somepkg.somemod.tests.testSomemodYYYY'.  Note that this means
+unit test module 'somepkg.somemod.tests.test_somemod'. Or if more than
+one set of unit tests is desired, multiple test modules of the form
+'somepkg.somemod.tests.test_somemodYYYY'.  Note that this means
 that your 'somemod' directory needs to have a 'tests' subdirectory,
 and that that subdirectory must have a (normally empty) '__init__.py'
 file in it.
 
-The file 'ut.py' in the root directory of the Z3 tree contains
-a skeleton file appropriate for using in building unit test
-modules.  If you use ut.py and follow the guidelines above,
-then your unit tests will automatically be run when 'test.py'
-is run.
-
 In your unit test class, begin all unit test methods with the string 
 'test'.
-If you use the !CleanUp class support (see the comments in 'ut.py'),
-make sure that your 'setUp' and 'tearDown' methods call the
-!CleanUp class's 'setUp' and 'tearDown' methods::
+If you use the CleanUp class support, make sure that your 'setUp'
+and 'tearDown' methods call the CleanUp class's 'setUp' and
+'tearDown' methods::
 
     class TestSomething(CleanUp):
         def setUp(self):
@@ -30,8 +24,9 @@ make sure that your 'setUp' and 'tearDown' methods call the
             #your teardown here
             CleanUp.tearDown(self)
 
-**Never** give your test methods a docstring!  Doing so makes it very difficult
-to find your test method when using the verbose output.  Use a comment instead.
+**Never** give your test methods a docstring! Doing so makes it very
+difficult to find your test method when using the verbose output.
+Use a comment instead.
 
 Call your test class TestSomething, never just Test.
 
@@ -42,8 +37,7 @@ to write test methods that exercise each individual method of
 the class.  It is a good idea to organize these tests according to
 the Interfaces implemented by the class under test.  In fact, it
 is often best to implement such tests in separate mixin classes,
-one class per Interface.  WritingInterfaceTests expands
-on this concept in more detail.
+one class per Interface.
 
 Within the unit tests themselves, the Zope style is to use
 the positive rather than the double negative assertions.
@@ -71,6 +65,3 @@ leads to more robust and general unit tests:
     can write a "helper function" to do the import and create and
     return instance(s) of the objects needed for testing,
     and call it from the start of each unit test.
-
-Other Best Practices suggestions welcome!
-