The basic principles of developing Brian are:
Coding conventions. We use the PEP-8 coding conventions for our code. Syntax is chosen as much as possible from the user point of view, to reflect the concepts as directly as possible. Ideally, a Brian script should be readable by someone who doesn’t know Python or Brian, although this isn’t always possible. Function and class names should be explicit rather than abbreviated.
Documentation. It is very important to maintain documentation. We use the Sphinx documentation generator tools. The documentation is all hand written. Sphinx source files are stored in the docs_sphinx folder in the repository, and compiled HTML files are stored in the docs folder. Most of the documentation is stored directly in the Sphinx source text files, but reference documentation for important Brian classes and functions are kept in the documentation strings of those classes themselves. This is automatically pulled from these classes for the reference manual section of the documentation. The idea is to keep the definitive reference documentation near the code that it documents, serving as both a comment for the code itself, and to keep the documentation up to date with the code.
In the code, every class or function should start with an explanation of what it does, unless it is trivial. A good idea is to use explicit names rather than abbreviations, so that you instantly understand what it is about. Inside a function, important chunks should also be commented.
Testing. Brian uses the nose package for its testing framework. Tests are stored in the brian/tests directory. Tests associated to a Brian module are stored in brian/tests/testinterface and tests of the mathematical correctness of Brian’s algorithms are stored in brian/tests/testcorrectness.
Errors. It is a good idea to start an important function (e.g. object initialisation) with a check of the arguments, and possibly issue errors. This way errors are more understandable by the user.
Enhancements. Brian uses a system parallel to the Python Enhancement Proposals (PEPs) system for Python, called Brian Enhancement Proposals (BEPs). These are stored in dev/BEPs. Ideas for new functionality for Brian are put in here for comment and discussion. A BEP typically includes:
We also use the Brian development mailing list.
First of all, you should register to the developers mailing list. If you want to modify existing modules, you should make sure that you work on the latest SVN version. We use the Eclipse IDE because it has a nice Python plugin (Pydev) and SVN plugin, but of course you can use your preferred IDE. The next step is to carefully read the guidelines in this guide.
Now that you wrote your code:
From that point, your patch will either be directly included in the svn or (more likely) will be first discussed in the mailing list.
New modules. New Brian modules typically start in the dev/ideas folder, then go to brian/experimental when they starting looking like modules. They move to the main folder when they are stable (especially the user syntax).