Programming guidelines - Revision history

Patsyblefebre: /* Members names */ format

2012-12-28T04:06:52Z

‎Members names: format

2012-12-28T04:05:19Z

‎Pylint: was renamed to gramps from src

2012-12-28T04:04:25Z

‎Docstrings: format

2012-12-28T04:02:13Z

‎Docstrings: update links

2012-12-28T04:01:02Z

‎Docstrings: update link

2012-12-24T08:29:59Z

‎Pylint: pylint has a new home http://www.pylint.org/

2012-09-30T19:28:38Z

‎Coding style

2011-10-19T09:36:22Z

‎Best practices

2011-10-14T03:58:05Z

‎Best practices

2011-10-14T03:56:47Z

‎Best practices

@@ Line 16: / Line 16: @@
 * 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>
+<pre>
-  def __private_function(self):
+def __private_function(self):
-      pass
+    pass
-−
-  def _protected_function(self):
+def _protected_function(self):
-      pass
+    pass
-</code>
+</pre>
 === Callbacks ===

@@ Line 82: / Line 82: @@
 * 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>src</code> directory. If import errors still occur, add a PYTHONPATH. Example usage:
+Note that you must run <code>pylint</code> in the <code>gramps</code> directory. If import errors still occur, add a PYTHONPATH. Example usage:
    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. Info on the codes can be found here: [http://pylint-messages.wikidot.com/all-codes]

@@ Line 64: / Line 64: @@
 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.
-<code>
+<pre>
-  class MyClass:
+class MyClass:
-      """
+    """
-      MyClass is a sample class.
+    MyClass is a sample class.
-      """
+    """
-−
-      def my_function(self):
+    def my_function(self):
-          """
+        """
-          The my_function task serves no purpose whatsoever.
+        The my_function task serves no purpose whatsoever.
-          """
+        """
-          pass
+        pass
-</code>
+</pre>
 == Pylint ==

@@ Line 60: / Line 60: @@
 :More info
-:* [http://sphinx.pocoo.org/markup/desc.html sphinx for python]
+:* [http://sphinx-doc.org/markup/desc.html sphinx for python]
-:* [http://sphinx.pocoo.org/rest.html doc with sphinx]
+:* [http://sphinx-doc.org/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.

@@ Line 57: / Line 57: @@
 * 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 [http://gramps.svn.sourceforge.net/viewvc/gramps/trunk/docs/ docs directory], for info read the [http://gramps.svn.sourceforge.net/viewvc/gramps/trunk/docs/README.txt?view=markup README.txt] file.
+* 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 [http://gramps.svn.sourceforge.net/viewvc/gramps/trunk/docs/ docs directory], for info read the [http://svn.code.sf.net/p/gramps/code/trunk/docs/README.txt README.txt] file.
 :More info

← Older revision		Revision as of 19:28, 30 September 2012
Line 29:		Line 29:

	<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>'.		<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>)
		+
		+	'''Important''': files in the gen submodule are '''not''' allowed to import files from the other submodules. So <code>gen</code> should be self-contained.
		+
		+	'''Important 2''': current code does not satisfy this rule yet, should be done by end of 2012

	== Class headers ==		== Class headers ==

@@ Line 76: / Line 76: @@
 * Reduce dependencies (imports) between files.
 [[Category:Developers/General]]
 [[Category:Developers/Quality Assurance]]

← Older revision		Revision as of 03:58, 14 October 2011
Line 78:		Line 78:

	[[Category:Developers/General]]		[[Category:Developers/General]]
		+	[[Category:Developers/Quality Assurance]]

@@ Line 73: / Line 73: @@
 == Best practices ==
-* Always develop with [http://www.gramps-project.org/wiki/index.php?title=Coding_for_translation language translation] in mind
+* Always develop with [[Coding_for_translation|language translation]] in mind
 * Reduce dependencies (imports) between files.
 [[Category:Developers/General]]