Programming guidelines

From Gramps
Revision as of 03:06, 5 September 2007 by Don (talk | contribs) (New page: Category:Developers/General As more and more people start editing the code, we need to establish a few guidelines to make sure the code remains maintainable. * Class headers. Each c...)
(diff) ← Older revision | Latest revision (diff) | Newer revision → (diff)
Jump to: navigation, search


As more and more people start editing the code, we need to establish a few guidelines to make sure the code remains maintainable.

  • 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.

 #------------------------------------------------------------
 #
 # MyClass
 #
 #------------------------------------------------------------

  • 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 epydoc format. This allows us to extract API documentation. Classes that are not core reusable classes do not have to follow this format, but should be documented using docstrings.

  class MyClass:
    """
    MyClass is a sample class.
    """
    
    def my_function(self):
       """
       The my_function task serves no purpose whatsoever.
       """
       pass

  • 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.

  def __private_function(self):
     pass
  
  def _protected_function(self):
     pass

  • Run pylint on your code before checking in, reasonably cleaning up the code.