[gnue] r7626 - trunk/gnue-common/doc/technotes

[reinhard]

Author: reinhard
Date: 2005-06-20 07:05:13 -0500 (Mon, 20 Jun 2005)
New Revision: 7626

Added:
   trunk/gnue-common/doc/technotes/00015.txt
Log:
Nitpicker's guide.


Added: trunk/gnue-common/doc/technotes/00015.txt
===================================================================
--- trunk/gnue-common/doc/technotes/00015.txt   2005-06-20 11:47:10 UTC (rev 
7625)
+++ trunk/gnue-common/doc/technotes/00015.txt   2005-06-20 12:05:13 UTC (rev 
7626)
@@ -0,0 +1,47 @@
+Title:   Nitpicker's checklist for code cleanup
+Status:  Current 
+Created: 2005-06-20
+Revised: 2005-06-20
+
+* svn propset svn:keywords Id
+
+* GPL header
+  - start with a short line describing the purpose of the file
+  - include $Id: $ line at the end
+
+* Docstrings for the module, for all classes and for all public functions
+
+* Reasonable exception classes
+
+* Docstrings for exceptions
+
+* Include a @raise line in function docstrings whenever appropriate
+
+* Include an "__all__ = [...]" line
+
+* Remove references to depreciated Python modules, especially types and string
+
+* ==== comments for classes or function groups, ---- comments for functions
+
+* Define a __repr__ () function for objects whenever reasonable
+
+* Naming of functions:
+  foo ():   public interface functions
+  _foo ():  non-public interface functions intended to be used by related
+            objects (e.g. ResultSet - RecordSet)
+  _foo_ (): virtual functions intended to be overwritten by descendants
+  __foo (): private functions
+  Keep the public interface as clean as possible!
+
+* Order of function definitions:
+  1. object system functions, like __init__, __repr__, __getitem__, __del__
+  2. overrides of inherited virtual functions
+  3. public iterface functions
+  4. stubs for newly-introduced virtual functions to be overridden by
+     descendants
+  Private functions come right after the public function that uses it; private
+  functions used at several places can go between 3. and 4.
+
+* Include reasonable debug messages with gDebug
+
+* Include checktype () checks for parameters in public functions