We really appreciate your help developing
welcome pull requests to the
devel branch. To help us more
quickly review your pull request, and to keep a consistent coding
style throughout, we ask that you please follow the below coding
styles (and that you aren’t offended if we modify your submission
so that it meets these styles).
BioSimSpace uses the Python programming language. Our aim is to provide a simple and robust API where unnecessary implementation details are hidden from the user.
“Hold on a second, this code isn’t very Pythonic!“
Indeed it is not. BioSimSpace is built on top of an existing C++ framework and the wrapped objects are designed to mimic the underlying C++ API. In addition, this is partly a design choice, since BioSimSpace is intended primarily to be used by novices, who may be unfamiliar with Python, or programming in general. We want to make it as easy as possible for these users to get up and running with molecular simulation. BioSimSpace also needs to be robust and portable, hence we need to use encapsulation to shield the user from unintended consequences.
With this in mind, we use the following coding conventions:
We follow a C++ style naming convention.
For example, to instantiate a minimisation protocol from the
import BioSimSpace as BSS protocol = BSS.Protocol.Minimisation()
(Note that sire BioSimSpace repository, on top of which BioSimSpace is built, has recently undergone a modernisation program and now has a fully PEP8-compliant API. We indent to move BioSimSpace towards using Python compliant API too, while preserving backwards compatibility.)
We use black to autoformat our Python code. Please use this if you plan on submitting code. They are easy to configure and use via your IDE (or from the command-line) and help ensure a consistent code style and minimise diffs during pull requests.
BioSimSpace is a collection of packages, e.g.
BioSimSpace.Protocol. Within each package is a set of modules that
implement the required functionality. Rather than directly exposing all of
the modules we choose to hide implementation details from the user. Instead
we use the package
__init__.py to selectively import the required
classes and functions.
Module files containing implementation details are prefixed with an underscore, i.e.
Where possible, external packages are hidden inside each module, e.g.
import mdtraj as _mdtraj
Each module file contains an
__all__variable that lists the specific items that should be imported.
__init__.pycan be used to safely expose the required functionality to the user with:
from module import *
This results in a clean API and documentation, with all extraneous information,
e.g. external modules, hidden from the user. This is important when working
interactively, since IPython and Jupyter
do not respect the
__all__ variable when auto-completing, meaning that the
user will see a full list of the available names when hitting tab. When
following the conventions above, the user will only be able to access the
exposed names. This greatly improves the clarity of the package, allowing
a new user to quickly determine the available functionality. Any user wishing
expose further implementation detail can, of course, type an underscore to
show the hidden names when searching.
BioSimSpace aims to provide a means of writing robust and portable workflow components (nodes). To this end, we choose to use an object oriented approach where data is encapsulated, with getters used to retrieve data from an object.
To avoid unintended consequences, getters that return mutable data types, e.g. lists and dictionaries, should return a copy of the data. This prevents the user unintentionally modifying the private data contained in the object. Setters should be used to explicitly modify member data.
# A class that holds a list of numbers. class MyClass(): # A private class member variable containing a list of numbers. _list = [1, 2, 3, 4, 5] def getList(self): return self._list # Create an instance of the class. c = MyClass() n = c.getList() print(n) [1, 2, 3, 4, 5] # Update n. n.append(6) # The private member data has been modified! print(c.getList()) [1, 2, 3, 4, 5, 6]
class MyClass(): # A private class member variable containing a list of numbers. _list = [1, 2, 3, 4, 5] def getList(self): return self._list.copy() # Create an instance of the class. c = MyClass() n = c.getList() print(n) [1, 2, 3, 4, 5] # Update n. n.append(6) # The private member data is untouched. print(c.getList()) [1, 2, 3, 4, 5]