54
edits
Changes
Add sections and improve the Pylint policies.
[[Category:Developers/General]]
== Coding Style ==
=== PEP8 ===
* Write [http://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 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
** TAB stops (if any) are at position 9,17,25,... (first column is 1)
=== Members Names ===* 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.<code> def __private_function(self): pass def _protected_function(self): pass</code> == Class headers. 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.
<code>
#------------------------------------------------------------
#------------------------------------------------------------
</code>
== Docstrings ==* Docstrings. Python provides a docstrings to document classes and functions. If the class is a class used by others (such as the RelLib classes), the docstrings should follow the [http://epydoc.sourceforge.net/manual-epytext.html epydoc] format. This allows us to extract [http://gramps-project.org/api3 API] documentation. Classes that are not core reusable classes do not have to follow this format, but should be documented using docstrings.
<code>
class MyClass:
pass
</code>
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. Try to obtain a score of minimum 9/10. Info on the codes can be found here: [http://www.logilab.org/card/pylintfeatures]
== 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.