Rev 2796: Document code layout stuff in http://sourcefrog.net/bzr/doc

[Martin Pool]

At http://sourcefrog.net/bzr/doc

------------------------------------------------------------
revno: 2796
revision-id: mbp at sourcefrog.net-20070905051221-ubcur9dfodsozr28
parent: pqm at pqm.ubuntu.com-20070905001648-0iigag4tq1u8mywn
committer: Martin Pool <mbp at sourcefrog.net>
branch nick: doc
timestamp: Wed 2007-09-05 15:12:21 +1000
message:
  Document code layout stuff
modified:
  doc/developers/HACKING.txt     HACKING-20050805200004-2a5dc975d870f78c
=== modified file 'doc/developers/HACKING.txt'
--- a/doc/developers/HACKING.txt	2007-08-28 06:59:20 +0000
+++ b/doc/developers/HACKING.txt	2007-09-05 05:12:21 +0000
@@ -624,12 +624,64 @@
 Coding Style Guidelines
 =======================
 
+Code layout
+-----------
+
 Please write PEP-8__ compliant code.  
 
+__ http://www.python.org/peps/pep-0008.html
+
 One often-missed requirement is that the first line of docstrings
 should be a self-contained one-sentence summary.
 
-__ http://www.python.org/peps/pep-0008.html
+We use 4 space indents for blocks, and never use tab characters.  (In vim,
+``set expandtab``.)
+
+Lines should be no more than 79 characters if at all possible.
+Lines that continue a long statement may be indented in either of 
+two ways:
+
+within the parenthesis or other character that opens the block, e.g.::
+
+    my_long_method(arg1,
+                   arg2,
+                   arg3)
+
+or indented by four spaces::
+
+    my_long_method(arg1,
+        arg2,
+        arg3)
+
+The first is considered clearer by some people; however it can be a bit
+harder to maintain (e.g. when the method name changes), and it does not
+work well if the relevant parenthesis is already far to the right.  Avoid
+this::
+
+     self.legbone.kneebone.shinbone.toebone.shake_it(one,
+                                                     two,
+                                                     three)
+
+but rather ::
+
+     self.legbone.kneebone.shinbone.toebone.shake_it(one,
+         two,
+         three)
+
+or ::
+
+     self.legbone.kneebone.shinbone.toebone.shake_it(
+         one, two, three)
+
+For long lists, we like to add a trailing comma and put the closing
+character on the following line.  This makes it easier to add new items in
+future::
+
+    from bzrlib.goo import (
+        jam,
+        jelly,
+        marmalade,
+        )
 
 
 Module Imports