Rev 2808: (mbp) coding standard and doc updates in file:///home/pqm/archives/thelove/bzr/%2Btrunk/

[Canonical.com Patch Queue Manager]

At file:///home/pqm/archives/thelove/bzr/%2Btrunk/

------------------------------------------------------------
revno: 2808
revision-id: pqm at pqm.ubuntu.com-20070910100551-cw3iuntfi1kwj8jg
parent: pqm at pqm.ubuntu.com-20070910085701-36pk2aye9gf2vc0t
parent: mbp at sourcefrog.net-20070906012710-fu7nkpp26k72a70n
committer: Canonical.com Patch Queue Manager <pqm at pqm.ubuntu.com>
branch nick: +trunk
timestamp: Mon 2007-09-10 11:05:51 +0100
message:
  (mbp) coding standard and doc updates
modified:
  bzrlib/builtins.py             builtins.py-20050830033751-fc01482b9ca23183
  doc/developers/HACKING.txt     HACKING-20050805200004-2a5dc975d870f78c
    ------------------------------------------------------------
    revno: 2795.1.3
    merged: mbp at sourcefrog.net-20070906012710-fu7nkpp26k72a70n
    parent: mbp at sourcefrog.net-20070905064242-642im0o3ookdlmqw
    committer: Martin Pool <mbp at sourcefrog.net>
    branch nick: doc
    timestamp: Thu 2007-09-06 11:27:10 +1000
    message:
      clarify spacing for function parameters
    ------------------------------------------------------------
    revno: 2795.1.2
    merged: mbp at sourcefrog.net-20070905064242-642im0o3ookdlmqw
    parent: mbp at sourcefrog.net-20070905051221-ubcur9dfodsozr28
    committer: Martin Pool <mbp at sourcefrog.net>
    branch nick: doc
    timestamp: Wed 2007-09-05 16:42:42 +1000
    message:
      emacs indent additions from vila
    ------------------------------------------------------------
    revno: 2795.1.1
    merged: 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 file 'bzrlib/builtins.py'
--- a/bzrlib/builtins.py	2007-09-10 02:18:14 +0000
+++ b/bzrlib/builtins.py	2007-09-10 10:05:51 +0000
@@ -3865,7 +3865,7 @@
 
     encoding_type = 'exact'
 
-    _see_also = ['merge', 'doc/configuration.txt']
+    _see_also = ['merge']
 
     takes_args = ['submit_branch?', 'public_branch?']
 

=== modified file 'doc/developers/HACKING.txt'
--- a/doc/developers/HACKING.txt	2007-09-06 02:39:24 +0000
+++ b/doc/developers/HACKING.txt	2007-09-10 10:05:51 +0000
@@ -624,12 +624,93 @@
 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,
+        )
+
+There should be spaces between function paramaters, but not between the
+keyword name and the value::
+
+    call(1, 3, cheese=quark)
+
+In emacs::
+
+    ;(defface my-invalid-face
+    ;  '((t (:background "Red" :underline t)))
+    ;  "Face used to highlight invalid constructs or other uglyties"
+    ;  )
+
+    (defun my-python-mode-hook ()
+     ;; setup preferred indentation style.
+     (setq fill-column 79)
+     (setq indent-tabs-mode nil) ; no tabs, never, I will not repeat
+    ;  (font-lock-add-keywords 'python-mode
+    ;                         '(("^\\s *\t" . 'my-invalid-face) ; Leading tabs
+    ;                            ("[ \t]+$" . 'my-invalid-face)  ; Trailing spaces
+    ;                            ("^[ \t]+$" . 'my-invalid-face)); Spaces only
+    ;                          )
+     )
+
+    (add-hook 'python-mode-hook 'my-python-mode-hook)
+
+The lines beginning with ';' are comments. They can be activated
+if one want to have a strong notice of some tab/space usage
+violations.
 
 
 Module Imports