Coding Conventions

The styling of our source is derived from PEP8 and the flake8 tool. There are, however, issues relating to patterns of usage which are not covered by that. Eventually this page will become our settled guidelines on these issues but for the moment it is a place to record discussions.

How to import a module

There are two basic ways to use a module, they can be imported: whole or in parts. Which you choose effects how you refer to the included objects.

If the whole module is imported then any part thereof must be specified by a full path.

import some.old.toot
...
if some.old.toot.gubbins():
    variable = some.old.toot.Thing()

On the other hand importing only parts of a module allow them to be referred to directly.

from some.old.toot import gubbins, Thing
...
if gubbins():
    variable = Thing()

The great advantage of the second approach is that it shortens the references which helps keep a lid on line length. The major down side is that it is not uncommon for modules to provide convenience functions such as open which share names with built-in objects. These references then become ambiguous. It is also slightly less clear where a thing comes from at first glance.

Conversesly the first approach is very clear on the origin of things and there is no chance of collisions with built-in objects. However it can lead to the source being messy and lines get long very fast.

Matthew says:

I tend to use the full import for module level functions but like the partial import for classes. The problem with this is when you want to do both.

How to span argument lists across lines

When an argument list, either in function definition or call, gets too long for a line it must be broken across lines. There are many different ways to achieve this but it would probably be best to agree on just one.

There are so many alternative approaches that instead of trying to list all or even some of them it's probably best just to present the ones we like and then have a discussion about those.

Matthew says:

I like to include the first argument on the first line and line up remaining arguments below it:

def foo(first,
        second,
        third):

I find the aligned argument start to be easy to track down whithout adding any more lines than necessary. It does lead to diff churn when adding arguments at the beginning and end but I don't consider that a problem as code is read far more often than it is written or reviewed.