Difference between revisions of "Programming guidelines"

From Gramps
Jump to: navigation, search
m (Fix tab vs space description ("whitespace" includes tabs))
(More explanation about spaces, TABs and indentation.)
Line 4: Line 4:
  
 
* Write [http://www.python.org/dev/peps/pep-0008/ PEP 8] compatible code! This is important to have a consistent, readable codebase.
 
* 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
  
* Do not use tabs. Use space characters. If you use an editor with settable tab stops, go into the preferences and change the tab behavior to use spaces only. In GRAMPS we use 4 spaces for indentation.
+
* 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
 +
** indentation is 4
 +
** TAB stops (if any) are at position 9,17,25,... (first column is 1)
  
 
* 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.
 
* 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.

Revision as of 09:42, 9 March 2008


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

  • Write 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
  • 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
    • indentation is 4
    • TAB stops (if any) are at position 9,17,25,... (first column is 1)
  • 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, and use the output to reasonably clean up the code. Note that you must run pylint in the src directory.
  • Reduce dependencies (imports) between files.