Rev 3897: (mbp) Developer documentation about when to add new exception classes in file:///home/pqm/archives/thelove/bzr/%2Btrunk/

[Canonical.com Patch Queue Manager]

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

------------------------------------------------------------
revno: 3897
revision-id: pqm at pqm.ubuntu.com-20081212012450-3gw576prpztxziib
parent: pqm at pqm.ubuntu.com-20081211215721-7er55v3goevwfz9w
parent: mbp at sourcefrog.net-20081212004341-1s5soiy7itgnif7w
committer: Canonical.com Patch Queue Manager <pqm at pqm.ubuntu.com>
branch nick: +trunk
timestamp: Fri 2008-12-12 01:24:50 +0000
message:
  (mbp) Developer documentation about when to add new exception classes
modified:
  doc/developers/HACKING.txt     HACKING-20050805200004-2a5dc975d870f78c
    ------------------------------------------------------------
    revno: 3882.4.2
    revision-id: mbp at sourcefrog.net-20081212004341-1s5soiy7itgnif7w
    parent: mbp at sourcefrog.net-20081212002306-oyljdsw9is6zkqf0
    committer: Martin Pool <mbp at sourcefrog.net>
    branch nick: doc-hacking
    timestamp: Thu 2008-12-11 16:43:41 -0800
    message:
      Tweak documentation of exception classes
    modified:
      doc/developers/HACKING.txt     HACKING-20050805200004-2a5dc975d870f78c
    ------------------------------------------------------------
    revno: 3882.4.1
    revision-id: mbp at sourcefrog.net-20081212002306-oyljdsw9is6zkqf0
    parent: pqm at pqm.ubuntu.com-20081205181554-ofrdnafloc43bxkh
    committer: Martin Pool <mbp at sourcefrog.net>
    branch nick: doc-hacking
    timestamp: Thu 2008-12-11 16:23:06 -0800
    message:
      Developer documentation about when to add new exception classes
    modified:
      doc/developers/HACKING.txt     HACKING-20050805200004-2a5dc975d870f78c
=== modified file 'doc/developers/HACKING.txt'
--- a/doc/developers/HACKING.txt	2008-12-09 09:22:11 +0000
+++ b/doc/developers/HACKING.txt	2008-12-12 01:24:50 +0000
@@ -886,6 +886,17 @@
 that exception specifically, or when it needs a substantially different
 format string.
 
+#. If it is something that a caller can recover from, a custom exception
+   is reasonable. 
+
+#. If it is a data consistency issue, using a builtin like
+   ``ValueError``/``TypeError`` is reasonable. 
+
+#. If it is a programmer error (using an api incorrectly)
+   ``AssertionError`` is reasonable. 
+
+#. Otherwise, use ``BzrError`` or ``InternalBzrError``.
+
 Exception strings should start with a capital letter and should not have a
 final fullstop.  If long, they may contain newlines to break the text.