Please observe the following coding standards when working on the codebase:
Docstrings quoted with """
Simple strings in source code should be quoted with '
Coding must follow a style guide. In case of Python it is pep8 and using the command line tool pep8 (or make pep8) to enforce this. The pep8 checks E121-E128 have been disabled until pep8 version 1.3 becomes widely available.
Comments should be complete sentences. If a comment is a phrase or sentence, its first word should be capitalized, unless it is an identifier that begins with a lower case letter (never alter the case of identifiers!). Comments should start with a # and a single space.
Adherence to regression/unit testing wherever possible (make test)
Use of github for revision control, issue tracking and management
Simple deployment procedure - all dependencies must be delivered with the plugin installer for QGIS or exist in standard QGIS installs.
Develop in the spirit of XP/Agile, i.e. frequent releases, continuous integration and iterative development. The master branch should always be assumed to represent a working demo with all tests passing.
All strings should be internationalisation enabled. Please see Internationalisation Support for details.
Code must pass a pylint validation (http://www.logilab.org/card/pylint_manual#what-is-pylint). You can test this using the make target make pylint. In some cases you may wish to override a line or group of lines so that they are not validated by lint. You can do this by adding either:
import foo # pylint: disable=W1203
or:
# pylint: disable=W1234
print 'hello'
print 'goodbye'
# pylint: enable=W1234
The relevant id (W1234) is provided on the output of the above mentioned lint command’s output. A complete list of codes is available at http://pylint-messages.wikidot.com/all-codes.
Note
You can globally ignore messages by adding them to pylintrc in the [MESSAGES CONTROL] section.
The following pylint messages have been thus globally excluded from the check. For a discussion of these see also github issue https://github.com/AIFDR/inasafe/issues/245.
variables. We may bring some back later.
All type I: Information only
W0201: Allow definition of class attributes outside the constructor.
W0212: Allow access to protected members (e.g. _show_system_info)
W0231: Allow classes without constructors.
W0232: Un-instantiated classes is a feature used in this project.
W0403: Relative imports are OK for modules that live in the same dir
W0511: Appearance of TODO and FIXME is not a sign of poor quality
E1101: Disable check for missing attributes.
E1103: This one does not understand numpy variables.
C0103: Allow mathematical variables such as x0 or A.
C0111: Allow missing docstrings in some cases
C0302: No restriction on the number of lines per module
It is of course possible to run all pylint checks on any part of the code if desired: E.g pylint safe/storage/raster.py
Each source file should include a standard header containing copyright, authorship and version metadata as shown in the exampled below.
Example standard header:
# -*- coding: utf-8 -*-
"""**One line description.**
.. tip::
Detailed multi-paragraph description...
"""
__author__ = 'Ole Nielsen <ole.moller.nielsen@gmail.com>'
__revision__ = '$Format:%H$'
__date__ = '01/11/2010'
__license__ = "GPL"
__copyright__ = 'Copyright 2012, Australia Indonesia Facility for '
__copyright__ += 'Disaster Reduction'
Note
Please see How did you embed the git version SHA1 into each .py file? for details on how the revision tag is replaced with the SHA1 for the file when the release packages are made.
All code should be self documenting. We used the following style for documenting functions and class methods:
def setKeywordDbPath(self, thePath):
"""Set the path for the keyword database (sqlite).
The file will be used to search for keywords for non local datasets.
Args:
* thePath: a valid path to a sqlite database. The database does
not need to exist already, but the user should be able to write
to the path provided.
Returns:
None
Raises:
None
"""
self.keywordDbPath = str(thePath)
Various other sphinx markup elements may be used in the docstrings too. For more information see also: http://thomas-cokelaer.info/tutorials/sphinx/docstring_python.html
For consistency of user experience, the user interfaces created in Risk in a Box should adhere to the QGIS Human Interface Guidelines (HIG) which are listed here for your convenience: