Style
=====

Indentation and blocks
----------------------

Python differs from most other programming languages because it uses indentation
to determine structure (that is, to determine what the :doc:`while
<control-flow/loops>` clause of a condition :abbr:`etc. (et cetera)`
represents). Most other languages use curly braces to do this. In the following
example, the indentation of lines 3–6 determines that they belong to the
``while`` statement:

.. code-block:: pycon
    :linenos:

    >>> x, y = 6, 3
    >>> while x > y:
    ...     x -= 1
    ...     if x == 4:
    ...         break
    ...     print(x)
    ...

Indentations to structure the code instead of curly braces takes a little
getting used to, but offers significant advantages:

* You can have neither missing nor too many brackets. Also, you no longer have
  to search for the bracket that might match earlier brackets.
* The visual structure of the code reflects its actual structure, making it much
  easier to understand.
* Python coding styles are mostly uniform; in other words, your code will mostly
  look very similar to that of others.

Comments
--------

Most of the time, anything that follows ``#`` is a comment and is ignored when
the code is executed. The obvious exception is ``#`` in a :doc:`string
<types/strings/index>`:

.. code-block:: pycon

    >>> x = "# This is a string and not a comment"

Basic Python style
------------------

In Python, there are relatively few restrictions on coding style, with the
obvious exception that code must be divided into blocks by indentation. Even in
this case, how (tabs or spaces) and how far indentation is used is not
prescribed. However, there are preferred stylistic conventions for Python, which
are contained in the *Python Enhancement Proposal* (PEP) 8. A selection of
Python conventions can be found in the following table:

+-----------------------+-------------------------------+-------------------------------+
| Context               | Recommendation                | Example                       |
+=======================+===============================+===============================+
| Module and package    | short, lower case,            | ``math``, ``sys``             |
| names                 | underscores only if necessary |                               |
+-----------------------+-------------------------------+-------------------------------+
| Function names        | lower case, underscores if    | ``my_func()``                 |
|                       | necessary                     |                               |
+-----------------------+-------------------------------+-------------------------------+
| Variable names        | lower case, with underscores  | ``my_var``                    |
|                       | if necessary                  |                               |
+-----------------------+-------------------------------+-------------------------------+
| Class names           | CamelCase notation            | ``MyClass``                   |
+-----------------------+-------------------------------+-------------------------------+
| Constant names        | Capital letters with          | ``PI``                        |
|                       | underscores                   |                               |
+-----------------------+-------------------------------+-------------------------------+
| Indentation           | Four spaces per level, no     |                               |
|                       | tabs                          |                               |
+-----------------------+-------------------------------+-------------------------------+
| Compare               | not explicitly with ``True``  | ``if my_var:``,               |
|                       | or ``False``, see also        | ``if not my_var:``            |
|                       | :doc:`control-flow/boolean`   |                               |
+-----------------------+-------------------------------+-------------------------------+

.. seealso::

    * :pep:`8`

I strongly recommend following the conventions of PEP 8. They are tried and
tested, and make your code easier to understand for yourself and others.