diff options
author | Georg Brandl <georg@python.org> | 2008-01-06 22:05:40 (GMT) |
---|---|---|
committer | Georg Brandl <georg@python.org> | 2008-01-06 22:05:40 (GMT) |
commit | 35f8861386794a823dfdbee3035f8ef00f0deddd (patch) | |
tree | 18703538b5c016611a9db2854a93073681c23ffa | |
parent | e9766c8acb6940274a21cf24e61808f6acfcf1e4 (diff) | |
download | cpython-35f8861386794a823dfdbee3035f8ef00f0deddd.zip cpython-35f8861386794a823dfdbee3035f8ef00f0deddd.tar.gz cpython-35f8861386794a823dfdbee3035f8ef00f0deddd.tar.bz2 |
Add tutorial section about coding style.
-rw-r--r-- | Doc/tutorial/controlflow.rst | 53 | ||||
-rw-r--r-- | Doc/tutorial/introduction.rst | 4 |
2 files changed, 52 insertions, 5 deletions
diff --git a/Doc/tutorial/controlflow.rst b/Doc/tutorial/controlflow.rst index 4869496..e42e23a 100644 --- a/Doc/tutorial/controlflow.rst +++ b/Doc/tutorial/controlflow.rst @@ -551,10 +551,57 @@ Here is an example of a multi-line docstring:: No, really, it doesn't do anything. +.. _tut-codingstyle: + +Intermezzo: Coding Style +======================== + +.. sectionauthor:: Georg Brandl <georg@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). diff --git a/Doc/tutorial/introduction.rst b/Doc/tutorial/introduction.rst index 3bbe53a..5e027a0 100644 --- a/Doc/tutorial/introduction.rst +++ b/Doc/tutorial/introduction.rst @@ -578,8 +578,8 @@ series as follows:: ... # 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 |