A rose by any other name

Use clear, descriptive variable names, including (and especially) internal variables not exposed to the user.

For instance, avoid names such as aa, NcD etc unless there is a specific reason. No need to be extra verbose (e.g. number_of_dimensions is overkill, D is ambiguous, n_dim or n_dimensions are good).

Reserve CamelCase (a variable name without spaces where each word starts with a capital letter) for Class names. For variable, use underscore_separated_words. Typically, all caps is reserved for global variable which are almost never used in Python DONOTUSETHISUNLESS YOUKNOWWHAT YOUAREDOING.

A common pitfall I often see, especially from researchers/students coding a paper, is to follow verbatim the notation from the paper being implemented. While variables such as the ubiquitous x are common in math, we try to avoid them in coding. Instead, try to give your variable descriptive and helpful names such as n_dim, ground_truth, prediction, etc.

Syntax: PEP8

Before you submit your changes, you should also make sure your code adheres to the style-guide of the project you are contributing to, as well as [PEP8]. Note that PEP stands for Python Enhancement Proposal. PEP8 is an early one establishing what has become the standard for the language. The easiest way to make sure your code is complient is with black:

pip install black
black .

As a side note, when in doubt, follow the established standards of the project you are contributing to, rather than rigidly follow a given rule.

Documentation

A crutial part of good code is its documentation. The same way you'd have a notation table in a paper, and prose to explain an equation. This consists in comments (where needed to explain a particularly complex/unintuitive line of code) and docstring, which details a function's (or class') role, as well as its input parameters, what it returns and potential notes and examples of use.

I tend to use the Numpy style. For instance, for a function, we expect a docstring with the following structure:

def function(arg):
   """One line description

   Longer description,
   possibly in several lines

   Parameters
   ----------
   arg : type
      description
      **Notice the space before and after the colon!**

   Returns
   -------
   variable : type
      description

   Examples
   --------
   text
   >>> code
   expected result

   Notes
   -----
   Detailed explanation
   """
   pass

Notes and Examples are optional, but always describe the function/class' role and input parameters.

In the docstring, use single backticks for variable's names: `variable`.

Double backticks are used for inline code: ``inline code``.

For blocks of code, use double colons, leave a white line and indent said lines of code

::

   block of code
   on
   several
   lines...

Unit-tests: if it's not tested, it's broken

Each new function should be accompanied by a small function that checks the function's behaviour for correctness. Ideallly you want to test for mathematical/algorithmic correctness and API correctness at least. I would go further and suggest you write the unit-test before you write the actual function. And everytime you fix / find a bug, ideally, add a test case to make sure it does not happen again in the future!

For a function foo, contained in module.py you should add a function test_module.py which contains one (or more) test function(s) for all the functions in that module (in our case, foo). This allows for continuous integration tests to be run automatically everytime a change is made in the repository and ensure the changes are not breaking any functionality.

I like to use PyTest for this, as I find it very intuitive and it allows me to easily run the tests without getting in my way.

That test should be in a file test_foo.py and look like this:

def test_foo():
   """Unit-test for foo

   Notice that the function does not take any argument
   """

You can simply run pytest in your folder to run all these tests.

We typically don't use the syntax:

if __name__ == '__main__':
   do something

This induces a bunch of unintuitive behaviours that lead to hard to debug issues (e.g. local imports failing, using a local module instead of looking in the global path, etc).

If you remember one thing, let it be this, quote, from Bruce Eckel:

If it is not tested, it is broken!

You might know Bruce from his excellent book Thinking in C++ [Eckel2000]. Why am I using Python then? And why am I quoting the author of a famous C++ book? Well, first of all, I started with C and C++ long before I made the jump to Python. A jump I do not regret, Python is much more adapted to my research - but that is a story for another post.

For now, I will leave you with these other quotes by Bruce Eckel:

Life is short

(You need Python)

and

Life's better without braces.

Do not abuse classes and inheritance

You might be tempted to adopt a Java or C++ approach to coding, but this is Python. Privilege composition over inheritance. In general try to keep the number of classes to a minimum, and do not create virtual (abstract) classes unless really justified.

As Zed Shaw puts it, in Learn Python the HARD WAY [LearnPythonShaw]: "Most of the uses of inheritance can be simplified or replaced with composition, and multiple inheritance should be avoided at all costs". He also gives the following three rules of thumb:

1. Avoid multiple inheritance at all costs, as it’s too complex to be useful reliably. If you’re stuck with it, then be prepared to know the class hierarchy and spend time finding where everything is coming from.
2. Use composition to package up code into modules that are used in many different unrelated places and situations.
3. Use inheritance only when there are clearly related reusable pieces of code that fit under a single common concept or if you have to because of something you’re using

Once again, in summary, the goal is to make the code easy to read and maintain, and save the readers/maintainers to have to browse recursively through the files to understand some odd behaviour.

Premature Optimization

You probably have head this quote before:

“The real problem is that programmers have spent far too much time worrying about efficiency in the wrong places and at the wrong times; premature optimization is the root of all evil (or at least most of it) in programming.”

It was written by Sir Tony Hoare and made famous by none other than Donald Knuth.

In practice: write a code that works and is well tested first. Then, benchmark to find the bottlenecks. Lastly, optimize.

The best way to end up with bad code or wrong code is to start optimizing too early. You may end up going down the rabbit hole and miss the important part. One obvious example is parallelism. You typically want to parallelize at the highest-level. Enabling parallelisation at a lower level would probably result in race conditions or unefficient code where the threads/processes are waiting for each other.

As always, apply good judgment: we are not saying that you should not think about optimization or put thoughts about efficiency during the design/planning phase [PrematureOptimizationFallacy] !

Communicate!

You might be surprised to hear that coding is actually a small portion of writing software. Most of the time should be spent designing, planning and, most importantly, communicating.

Communication is core to any good collorative effort, especially software. Communicate efficiently and often. Don't go off coding what you think is needed in the way you think is best without talking to others: it is the best way to add work for everyone. In that way, failure to communicate could be seen as a special case of premature optimization.

Finally, remember that everyone is here to contribute to the same project and make it successful - be kind and assume best intentions. A lot of subtelty is lost when communicated through messages or emails. If you are having a bad day, it's ok, it happens, but take time of and do not take it out on others.