4,861
edits
Changes
m
→Members names: format
* Private class functions (functions that cannot be called outside the class) should be preceded with two underscores.
* Protected functions (functions that can only be called by the class or derived classes) should be preceded with one underscore.
<codepre> def __private_function(self): pass def _protected_function(self): pass</codepre>
=== Callbacks ===
<code>pylint</code> does not check that arguments are used when methods are named in this way. This is useful to avoid the <code>pylint</code> warning: 'W0613: Unused argument <arg>'.
=== Imports ===
The top module is called gramps, and it has following submodules:
# gen
# cli
# gui
# plugins
The other dirs should not contain code, or are for testing.
Within a submodule, only relative imports are allowed of the own submodule (so starting with . or with a module of the own directory), and absolute imports of other submodules (so starting with <code>gramps.</code>)
'''Important''': files in the gen submodule are '''not''' allowed to import files from the other submodules. So <code>gen</code> should be self-contained.
'''Important 2''': current code does not satisfy this rule yet, should be done by end of 2012
== Class headers ==
* Python provides a docstrings to document classes and functions. If the class is a class used by others (such as the [http://www.gramps-project.org/docs/gen/gen_lib.html#module-gen.lib gen lib] classes), the docstrings should follow the restructuredtext ([http://docutils.sourceforge.net/docs/user/rst/quickstart.html#structure rst]) format. This allows us to extract [http://www.gramps-project.org/docs/ API] documentation using sphinx.
* Apart from adding doc strings to classes and functions, also the api generating rst files must be edited so as to extract the documentation. These files are in the [http://gramps.svn.sourceforge.net/viewvc/gramps/trunk/docs/ docs diretorydirectory], for info read the [http://grampssvn.svncode.sourceforgesf.net/viewvcp/gramps/code/trunk/docs/README.txt?view=markup README.txt] file.
:More info
:* [http://sphinx.pocoo-doc.org/markup/desc.html sphinx for python]:* [http://sphinx.pocoo-doc.org/rest.html doc with sphinx]
Classes that are not core reusable classes do not have to follow this format (although we encourage you do), but should be documented using docstrings.
<codepre> class MyClass: """ MyClass is a sample class. """ def my_function(self): """ The my_function task serves no purpose whatsoever. """ pass</codepre>
== Pylint ==
* Any changes to existing files with a Pylint score lower than 9 shall not reduce the Pylint score. It is expected that over time, this policy will cause all files to eventually have a score of 9 or higher.
Note that you must run <code>pylint</code> in the <code>srcgramps</code> directory. If import errors still occur, add a PYTHONPATH. Example usage:
me@laptop:~/programs/trunk/src$ PYTHONPATH=plugins/lib/ pylint --include-ids=y --reports=y plugins/mapservices/googlemap.py
Set reports to n to have less output. Info on the codes can be found here: [http://wwwpylint-messages.logilabwikidot.orgcom/card/pylintfeaturesall-codes]
== Best practices ==
* Always develop with [http://www.gramps-project.org/wiki/index.php?title=[Coding_for_translation |language translation]] in mind
* Reduce dependencies (imports) between files.
* Think on [[Accessibility]].
[[Category:Developers/General]]
[[Category:Developers/Quality Assurance]]
