[Python-checkins] r59796 - python/trunk/Doc/tutorial/controlflow.rst python/trunk/Doc/tutorial/introduction.rst

[georg.brandl]

Author: georg.brandl
Date: Sun Jan  6 23:05:40 2008
New Revision: 59796

Modified:
   python/trunk/Doc/tutorial/controlflow.rst
   python/trunk/Doc/tutorial/introduction.rst
Log:
Add tutorial section about coding style.


Modified: python/trunk/Doc/tutorial/controlflow.rst
==============================================================================
--- python/trunk/Doc/tutorial/controlflow.rst	(original)
+++ python/trunk/Doc/tutorial/controlflow.rst	Sun Jan  6 23:05:40 2008
@@ -551,10 +551,57 @@
        No, really, it doesn't do anything.
 
 
+.. _tut-codingstyle:
+
+Intermezzo: Coding Style
+========================
+
+.. sectionauthor:: Georg Brandl <georg at python.org>
+.. index:: pair: coding; style
+
+Now that you are about to write longer, more complex pieces of Python, it is a
+good time to talk about *coding style*.  Most languages can be written (or more
+concise, *formatted*) in different styles; some are more readable than others.
+Making it easy for others to read your code is always a good idea, and adopting
+a nice coding style helps tremendously for that.
+
+For Python, :pep:`8` has emerged as the style guide that most projects adher to;
+it promotes a very readable and eye-pleasing coding style.  Every Python
+developer should read it at some point; here are the most important points
+extracted for you:
+
+* Use 4-space indentation, and no tabs.
+
+  4 spaces are a good compromise between small indentation (allows greater
+  nesting depth) and large indentation (easier to read).  Tabs introduce
+  confusion, and are best left out.
+
+* Wrap lines so that they don't exceed 79 characters.
+
+  This helps users with small displays and makes it possible to have several
+  code files side-by-side on larger displays.
+
+* Use blank lines to separate functions and classes, and larger blocks of
+  code inside functions.
+
+* When possible, put comments on a line of their own.
+
+* Use docstrings.
+
+* Use spaces around operators and after commas, but not directly inside
+  bracketing constructs: ``a = f(1, 2) + g(3, 4)``.
+
+* Name your classes and functions consistently; the convention is to use
+  ``CamelCase`` for classes and ``lower_case_with_underscores`` for functions
+  and methods.  Always use ``self`` as the name for the first method argument.
+
+* Don't use fancy encodings if your code is meant to be used in international
+  environments.  Plain ASCII works best in any case.
+
 
 .. rubric:: Footnotes
 
-.. [#] Actually, *call by object reference* would be a better description, since if a
-   mutable object is passed, the caller will see any changes the callee makes to it
-   (items inserted into a list).
+.. [#] Actually, *call by object reference* would be a better description,
+   since if a mutable object is passed, the caller will see any changes the
+   callee makes to it (items inserted into a list).
 

Modified: python/trunk/Doc/tutorial/introduction.rst
==============================================================================
--- python/trunk/Doc/tutorial/introduction.rst	(original)
+++ python/trunk/Doc/tutorial/introduction.rst	Sun Jan  6 23:05:40 2008
@@ -578,8 +578,8 @@
    ... # the sum of two elements defines the next
    ... a, b = 0, 1
    >>> while b < 10:
-   ...       print b
-   ...       a, b = b, a+b
+   ...     print b
+   ...     a, b = b, a+b
    ... 
    1
    1