Changes

Jump to: navigation, search

Programming guidelines

633 bytes added, 03:22, 26 April 2019
Pylint
=== PEP8 ===
* Write [httphttps://www.python.org/dev/peps/pep-0008/ PEP 8] compatible code! This is important to have a consistent, readable codebase.
** it is not explicit in PEP8, but we like a space after a comma
=== Tabs ===
* Do not use TABs. Use space characters. In GRAMPS Gramps we use 4 spaces for indentation. This does not mean you must set your TAB stops to 4. TABs and indents are not the same thing. Most editors have a configuration option to set indentation and TAB stops. Be careful to just set the '''indentation''' to 4, which automatically means it has to be '''spaces'''. (TABs are still necessary, in Makefiles for example, and they '''have to''' be equivalent to 8 spaces, '''always'''.) To summarize:
** uses spaces, no TABs
** indentation is 4
* 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>)
 
{{man note|Important:|files in the gen submodule are '''not''' allowed to import files from the other submodules. So <code>gen</code> should be self-contained.}}
== Class headers ==
* Each class should have a simple header to help mark it in the file. This is not used for documentation - it is used to help find the class when multiple classes exist in the same file.
<codepre> #------------------------------------------------------------ # # MyClass # #------------------------------------------------------------</codepre>
== Docstrings ==
* 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 [httphttps://gramps.svn.sourceforgegithub.netcom/viewvcgramps-project/gramps/trunktree/master/docs/ docs diretorydirectory], for info read the [httphttps://gramps.svn.sourceforgegithub.netcom/viewvcgramps-project/gramps/trunkblob/master/docs/README.txt?view=markup /docs/README.txt] file.
:More info
:* [http://www.sphinx.pocoo-doc.org/en/stable/markup/desc.html sphinx Sphinx for python]:* [http://www.sphinx.pocoo-doc.org/en/stable/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/trunkmaster/src$ PYTHONPATH=plugins/lib/ pylint --include-ids=y --reports=y plugins/mapservices/googlemap.pySet reports to '''n ''' to have less output. Info Information on the meaning of codes can be found here: * [http://wwwpylint-messages.logilabwikidot.orgcom/card/pylintfeaturesall-codes All codes], PyLint Messages: and what they're trying to tell you
== 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]]
301
edits

Navigation menu