Develop
Overview
- Getting the latest source code
- Developing a plug-in
- Source-code architecture
- Coding-style guidelines
Getting the latest source code
The OpenSesame source code is hosted on GitHub:
GitHub provides a straightforward way for collaborating on a project. If you’re not familiar with GitHub, you may want to take a look at their help site: http://help.github.com/.
The best (and easiest) way to contribute code is as follows:
- Create a GitHub account.
- Create a fork of OpenSesame https://github.com/smathot/OpenSesame.
- Modify your fork.
- Send a ‘pull request’, asking for your changes to be merged back into the main repository.
The two main branches of OpenSesame are:
mastercontains reasonably stable code.playgroundcontains potentially unstable code.
Developing a plug-in
For plug-in development, see:
Source-code architecture
For a description of the OpenSesame source-code architecture, see:
Coding-style guidelines
The goal is to maintain a readable and consistent code base. Therefore, please consider the following style guidelines when contributing code:
Exception handling
Exceptions should be handled via the libopensesame.exceptions.osexception class. For example:
from libopensesame.exceptions import osexception
raise osexception(u'An error occurred')
Printing debug output
Debug output should be handled via libopensesame.debug.msg(), and is shown only when OpenSesame is started with the --debug command-line argument. For example:
from libopensesame import debug
debug.msg(u'This will be shown only in debug mode')
Indentation
Indentation should be tab based. This is the most important style guideline of all, because mixed indentation causes trouble and is time consuming to correct.
Names, doc-strings, and line wrapping
- Names should be lower case, with words separated by underscorses.
- Each function should be accompanied by an informative doc string, of the format shown below. If a doc-string is redundant, for example, because a function overrides another function that has a doc-string, please indicate where the full doc-string can be found.
- Please do not have lines of code extend beyond 79 characters (where a tab counts as 4 characters), with the exception of long strings that are awkward to break up.
def a_function(argument, keyword=None):
"""
desc:
This is a YAMLDoc-style docstring, which allows for a full specification
of arguments. See also <https://github.com/smathot/python-yamldoc>.
arguments:
argument: This is an argument.
keywords:
keyword: This is a keyword.
returns:
This function returns some values.
"""
pass
def a_simple_function():
"""This is a simple doc-string"""
pass
Unicode and strings
Assure that all functionality is Unicode safe. For new code, use only Unicode strings internally.
my_value = 'a string' # not preferred
my_value = u'a string' # preferred
For more information, see:
Other
With the exception of the guidelines shown above, please adhere to the following standard:
