[Checkins] SVN: zope3docs/ Re-order, improve section headings, improve wording.
Christian Theune
ct at gocept.com
Thu Feb 19 12:28:37 EST 2009
Log message for revision 96787:
Re-order, improve section headings, improve wording.
Changed:
_U zope3docs/
U zope3docs/source/codingstyle/python-style.rst
-=-
Property changes on: zope3docs
___________________________________________________________________
Modified: bzr:revision-info
- timestamp: 2009-02-19 15:58:18.849999905 +0100
committer: Christian Theune <ct at gocept.com>
properties:
branch-nick: zope3docs.bzr
+ timestamp: 2009-02-19 16:08:24.144000053 +0100
committer: Christian Theune <ct at gocept.com>
properties:
branch-nick: zope3docs.bzr
Modified: bzr:file-ids
- source/codingstyle/index.rst 96696 at 62d5b8a3-27da-0310-9561-8e5933582275:zope3docs:source%2Fcodingstyle%2Findex.rst
source/codingstyle/python-style.rst 96696 at 62d5b8a3-27da-0310-9561-8e5933582275:zope3docs:source%2Fcodingstyle%2Fpython-style.rst
+ source/codingstyle/python-style.rst 96696 at 62d5b8a3-27da-0310-9561-8e5933582275:zope3docs:source%2Fcodingstyle%2Fpython-style.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
24 ct at gocept.com-20090219134127-4xq75osx1qizp1lh
25 ct at gocept.com-20090219134620-3kaefpqounb7me7f
26 ct at gocept.com-20090219145818-u7qndkg2cjev8a2q
+ 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
25 ct at gocept.com-20090219134620-3kaefpqounb7me7f
26 ct at gocept.com-20090219145818-u7qndkg2cjev8a2q
27 ct at gocept.com-20090219150824-7xz32ylkrdfil1dj
Modified: zope3docs/source/codingstyle/python-style.rst
===================================================================
--- zope3docs/source/codingstyle/python-style.rst 2009-02-19 17:28:34 UTC (rev 96786)
+++ zope3docs/source/codingstyle/python-style.rst 2009-02-19 17:28:37 UTC (rev 96787)
@@ -2,24 +2,28 @@
======
The general rule when writing Python code is to follow PEP 8. The rules
-given below override what is said in `PEP 8`_.
+given later in this document override what is said in `PEP 8`_.
-.. note::
- Please be aware that PEP 8 recommends module-level consistency over blind
- rule-following. Zope 3 has been around for a while and older code may have
- been written with a different set of rules.
- modules might not match the current rules. In that case, please make a
- conscious decision about a reasonable level of consistency.
+Be tolerant of code that doesn't follow these conventions: our code base
+has been evolving over years and doesn't always match the current style
+as we update these rules. Also, we want to reuse software written for
+other projects that do not adhere to our rules.
+Remember that PEP 8 explicitly allows breaking a rule in the interest of
+keeping code consistent.
-License statement and module docstring
---------------------------------------
+A reasonable goal is that code covered by the ZPL should follow these
+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 will contain a reference about version control status. The
-example given is valid for at least CVS and Subversion.
+The docstring should contain a reference about version control status.
+The example given is valid for at least CVS and Subversion.
Here is the template::
@@ -58,28 +62,48 @@
count as published? The FSF seemed to understand inclusions in
release tarballs as publications.
-Interfaces
+
+Whitespace
----------
-Interface names adhere to PEP 8's naming of classes, except that they
-are prefixed with a capital ``I``, as in ``IMagicThing``.
+Trailing whitespace should not occur, nor should blank lines at the end
+of files.
-One function of interfaces is to document functionality, so be very
-verbose with the documentation strings.
-All public interfaces should go into a file called ``interfaces.py``.
-"Public" interfaces are those that you expect to be implemented more
-than once. Interfaces that are likely to be implemented only once, like
-``IGlobalAdapterService``, should live in the same module as their
-implementation.
+Import statements
+-----------------
+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
+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.
+
.. note::
- TODO clarify whether the single/multiple implementation rule holds.
+ TODO This rule has been recommended by Jim but hasn't been
+ officially established.
- TODO there has been discussion about whether imperative or
- present tense is to be preferred for describing interfaces. The
- discussion was not resolved.
+Refrain from using relative imports. Instead of::
+
+ 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.
+
+
Attribute and method names
--------------------------
@@ -125,11 +149,12 @@
typically spelled with ``mixedCase``.
.. note::
- TODO This rule needs clarification.
+ TODO This rule needs clarification. What is a global variable
+ anyway? It's not a constant AFAICT.
-Avoid single-letter variables
------------------------------
+Local variables
+---------------
Single-letter variable names should be avoided unless:
@@ -141,64 +166,44 @@
variables.
-Imports
--------
+``try``/``except`` blocks
+-------------------------
-All imports should be at the top of the module, after the module
-docstring and/or comments, but before module globals.
+``try`` blocks should cover as little code as possible. ``except``
+statements should match exceptions as specific as possible.
-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
-the top of the file to flag that this was done.
+For example, if you are converting a value to an ``int``, and you want
+to catch conversion errors, you need only catch ``ValueError``. Be sure
+to do the minimum possible between your ``try:`` and ``except
+ValueError:`` statements::
-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.
+ try:
+ int(x)
+ except ValueError:
+ ...
-.. note::
- TODO This rule has been recommended by Jim but hasn't been
- officially established.
+Interfaces
+----------
-Refrain from using relative imports. Instead of::
+Interface names adhere to PEP 8's naming of classes, except that they
+are prefixed with a capital ``I``, as in ``IMagicThing``.
- import foo # from same package
+One function of interfaces is to document functionality, so be very
+verbose with the documentation strings.
-you can write::
+All public interfaces should go into a file called ``interfaces.py``.
+"Public" interfaces are those that you expect to be implemented more
+than once. Interfaces that are likely to be implemented only once, like
+``IGlobalAdapterService``, should live in the same module as their
+implementation.
- 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.
+ TODO clarify whether the single/multiple implementation rule holds.
- Relative imports should be avoided, I'm not sure about the style
- once we start getting real relative imports from Python.
+ TODO there has been discussion about whether imperative or
+ present tense is to be preferred for describing interfaces. The
+ discussion was not resolved.
-Catch specific errors, write small ``try`` blocks
--------------------------------------------------
-If you are converting a value to an ``int``, and you want to catch
-conversion errors, you need only catch ``ValueError``. Be sure to do the
-minimum possible between your ``try:`` and ``except ValueError:``
-statements.
-
-
-Don't leave trailing whitespace
--------------------------------
-
-Trailing whitespace should not occur, nor should blank lines at the end
-of files.
-
-
-Be tolerant
------------
-
-Be tolerant of code that doesn't follow these conventions. We want to
-reuse lots of software written for other projects, which may not follow
-these conventions.
-
-A reasonable goal is that code covered by the ZPL should follow these
-conventions.
-
-
.. _`PEP 8`: http://www.python.org/dev/peps/pep-0008/
More information about the Checkins
mailing list