============

Coding guide

============

General coding conventions

==========================

In general, we'll try to follow the standard Python style conventions as

described in Python's PEP 8 [PEP8]_, the official Python Style Guide.

Other general comments:

* In a large file, top level classes and functions should be separated by 2

lines to make it easier to separate them visually.

* Use 4 spaces for indentation, **never** use hard tabs.

* Keep the ordering of methods the same in classes that have the same methods.

This is particularly true for classes that implement similar interfaces and

for interfaces that are similar.

Naming conventions

==================

In terms of naming conventions, we'll follow the guidelines of PEP 8 [PEP8]_.

Some of the existing code doesn't honor this perfectly, but for all new

IPython code (and much existing code is being refactored), we'll use:

* All ``lowercase`` module names.

* ``CamelCase`` for class names.

* ``lowercase_with_underscores`` for methods, functions, variables and

attributes.

This may be confusing as some of the existing codebase uses a different

convention (``lowerCamelCase`` for methods and attributes). Slowly, we will

move IPython over to the new convention, providing shadow names for backward

compatibility in public interfaces.

There are, however, some important exceptions to these rules. In some cases,

IPython code will interface with packages (Twisted, Wx, Qt) that use other

conventions. At some level this makes it impossible to adhere to our own

standards at all times. In particular, when subclassing classes that use other

naming conventions, you must follow their naming conventions. To deal with

cases like this, we propose the following policy:

* If you are subclassing a class that uses different conventions, use its

naming conventions throughout your subclass. Thus, if you are creating a

Twisted Protocol class, used Twisted's

``namingSchemeForMethodsAndAttributes.``

* All IPython's official interfaces should use our conventions. In some cases

this will mean that you need to provide shadow names (first implement

``fooBar`` and then ``foo_bar = fooBar``). We want to avoid this at all

costs, but it will probably be necessary at times. But, please use this

sparingly!

Implementation-specific *private* methods will use

``_single_underscore_prefix``. Names with a leading double underscore will

*only* be used in special cases, as they makes subclassing difficult (such

names are not easily seen by child classes).

Occasionally some run-in lowercase names are used, but mostly for very short

names or where we are implementing methods very similar to existing ones in a

base class (like ``runlines()`` where ``runsource()`` and ``runcode()`` had

established precedent).

The old IPython codebase has a big mix of classes and modules prefixed with an

explicit ``IP``. In Python this is mostly unnecessary, redundant and frowned

upon, as namespaces offer cleaner prefixing. The only case where this approach

is justified is for classes which are expected to be imported into external

namespaces and a very generic name (like Shell) is too likely to clash with

something else. However, if a prefix seems absolutely necessary the more

specific ``IPY`` or ``ipy`` are preferred.

.. [PEP8] Python Enhancement Proposal 8. http://www.python.org/peps/pep-0008.html

Attribute declarations for objects

==================================

In general, objects should declare in their *class* all attributes the object

is meant to hold throughout its life. While Python allows you to add an

attribute to an instance at any point in time, this makes the code harder to

read and requires methods to constantly use checks with hasattr() or try/except

calls. By declaring all attributes of the object in the class header, there is

a single place one can refer to for understanding the object's data interface,

where comments can explain the role of each variable and when possible,

sensible deafaults can be assigned.

.. Warning::

If an attribute is meant to contain a mutable object, it should be set to

``None`` in the class and its mutable value should be set in the object's

constructor. Since class attributes are shared by all instances, failure

to do this can lead to difficult to track bugs. But you should still set

it in the class declaration so the interface specification is complete and

documdented in one place.

A simple example::

class foo:

# X does..., sensible default given:

x = 1

# y does..., default will be set by constructor

y = None

# z starts as an empty list, must be set in constructor

z = None

def __init__(self, y):

self.y = y

self.z = []

New files

=========

When starting a new file for IPython, you can use the following template as a

starting point that has a few common things pre-written for you. The template

is included in the documentation sources as

:file:`docs/sources/development/template.py`:

.. literalinclude:: template.py