Changes between Version 12 and Version 13 of CodingStandards

Timestamp:

2011-06-30T00:02:08Z (13 years ago)

Author:

zooko

Comment:

coding standards update!

CodingStandards

@@ -18 +18 @@
 
 {{{
-# Copyright (c) 2009 Allmydata, Inc.
+# Copyright (c) 2011 The Tahoe-LAFS Software Foundation
 # This file is part of Tahoe-LAFS; see doc/about.html for licensing terms.
 
@@ -34 +34 @@
 }}}
 
+ * Put two blank lines between classes.
  * Feel free to ignore the part of PEP-8 that says to put each module import on a separate line, but don't import modules from multiple separate packages on the same line.
  * Ignore the part of PEP-257 which says to put the trailing {{{"""}}} of a multi-line docstring on a separate line separated by a blank line.  (That rule appears to have been motivated by a limitation of Emacs which has been fixed.)
@@ -94 +95 @@
 Now you can put {{{assert self._assert_consistency()}}} everywhere in your class where the class ought to be in an internally consistent state. For example, at the beginning of every externally-callable method. This technique can be very valuable in developing a complex class -- it catches bugs early, it isolates bugs into specific code paths, and it clarifies the internal structure of the class so that other developers can hack on it without subtle misunderstandings.
 
+=== configuration ===
+
+==== minimizing configuration ====
+
+ * Do not implement configuration files for modules or libraries -- code that is going to be used by other code. Only applications -- code that is going to be used by humans -- have configuration files. Modules and libraries get "configured" by the code that calls them, for example by passing arguments to their constructors.
+ * If there are constant values which end-users do not need to modify, then do not make them configurable, but put them in all-caps variables at the beginning of the Python file in which they are used.
+ * Design algorithms so that they have as few "voodoo constants" and "tweakable parameters" as possible.
+
+==== how to implement configuration ====
+
+Whether in application code or in library code, never pass configuration values via a configuration object. Instead use Python parameters. For example -- here's another real-life example -- do not write
+
+{{{
+class BlockStore:
+    def __init__(self, confdict={}, recoverdb=True, name='*unnamed*'):
+        if confdict.has_key('MAX_MEGABYTES'):
+            self.maxspace = (2**20) * int(confdict.get('MAX_MEGABYTES'))
+        else:
+            self.maxspace = None
+        self.basepath = os.path.abspath(confdict.get("PATH", ""))
+        self.maintainertype = confdict.get("MAINTAINER", "rnd").lower()
+        self.backendtype = confdict.get("BACKEND", "flat").lower()
+}}}
+
+, but instead write
+
+{{{
+class BlockStore:
+    def __init__(self, maxspace=None, path="", maintainertype="rnd", backendtype="flat", recoverdb=True, name='*unnamed*'):
+        self.basepath = os.path.abspath(path)
+        self.maintainertype = maintainertype
+        self.backendtype = backendtype
+}}}
+.
+
+
 ==== assertion policy ====
 
@@ -144 +181 @@
 
 
-=== configuration ===
-
-==== minimizing configuration ====
-
- * Do not implement configuration files for modules or libraries -- code that is going to be used by other code. Only applications -- code that is going to be used by humans -- have configuration files. Modules and libraries get "configured" by the code that calls them, for example by passing arguments to their constructors.
- * If there are constant values which end-users do not need to modify, then do not make them configurable, but put them in all-caps variables at the beginning of the Python file in which they are used.
- * Design algorithms so that they have as few "voodoo constants" and "tweakable parameters" as possible.
-
-==== how to implement configuration ====
-
-Whether in application code or in library code, never pass configuration values via a configuration object. Instead use Python parameters. For example -- here's another real-life example -- do not write
-
-{{{
-class BlockStore:
-    def __init__(self, confdict={}, recoverdb=True, name='*unnamed*'):
-        if confdict.has_key('MAX_MEGABYTES'):
-            self.maxspace = (2**20) * int(confdict.get('MAX_MEGABYTES'))
-        else:
-            self.maxspace = None
-        self.basepath = os.path.abspath(confdict.get("PATH", ""))
-        self.maintainertype = confdict.get("MAINTAINER", "rnd").lower()
-        self.backendtype = confdict.get("BACKEND", "flat").lower()
-}}}
-
-, but instead write
-
-{{{
-class BlockStore:
-    def __init__(self, maxspace=None, path="", maintainertype="rnd", backendtype="flat", recoverdb=True, name='*unnamed*'):
-        self.basepath = os.path.abspath(path)
-        self.maintainertype = maintainertype
-        self.backendtype = backendtype
-}}}
-.
-
-
 == official Python standards ==