The basic principles of developing Brian are:
- For the user, the emphasis is on making the package flexible, readable and easy to use. See the paper “The Brian simulator” in Frontiers in Neuroscience for more details.
- For the developer, the emphasis is on keeping the package maintainable by a small number of people. To this end, we use stable, well maintained, existing open source packages whenever possible, rather than writing our own code.
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.
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
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.
Brian uses the nose package
for its testing framework. Tests are stored in the
Tests associated to a Brian module are stored in
and tests of the mathematical correctness of Brian’s algorithms are stored in
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.
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:
- How the feature will look from user point of view, with example scripts.
- Detailed implementation ideas and options.
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:
- Write a test for it in
brian/tests/testinterface. If it is a new module, create a new file
- Write documentation, both in the file (see how it’s done in existing modules)
and, if appropriate, in the relevant file in
docs_sphinx. We use the Sphinx documentation generator tools. If you want to see how it looks, generate the html docs by executing
dev/tools/docs/build_html.py. The html files will then be in
- If it is a significant feature, write an example script in
examplesand insert a line in
- Create a patch file. For example with Eclipse, right-click on the Brian project, then Team > Create Patch > Save in filesystem, then Next > Project.
- Send your patch as an attachment to the developers mailing list and make sure the subject of your message starts with [PATCH]. Then describe your patch in your message.
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 Brian modules typically start in the
dev/ideas folder, then go to
when they starting looking like modules. They move to the main folder when they are
stable (especially the user syntax).