diff --git a/Doc/tutorial/controlflow.rst b/Doc/tutorial/controlflow.rst index 486949610ae..e42e23a4b94 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 +.. 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 3bbe53a22dd..5e027a06110 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