Changes

Jump to: navigation, search

Programming guidelines

363 bytes added, 04:30, 29 April 2009
Add sections and improve the Pylint policies.
[[Category:Developers/General]]
As more and more people start editing the codeIn a multi-programmer environment, we need it is important to establish a few follow common coding guidelines to make sure the code remains maintainable.
== 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>
* 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>== Pylint ==* Run <code>pylint</code> on your code before checking in. * New files shall have a Pylint score of 9 or higher. New files will not be accepted if they have a Pylint score lower than 9.* Any changes to existing files with a Pylint score lower than 9 shall not reduce the Pylint score. It is expected that over time, and use the output this policy will cause all files to reasonably clean up the codeeventually have a score of 9 or higher.  Note that you must run <code>pylint</code> in the <code>src</code> directory. If import errors still occur, add a PYTHONPATH. Example usage:
[email protected]:~/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.
54
edits

Navigation menu