← Back to branch summary

~bzr-pqm/bzr/bzr.dev

« back to all changes in this revision

Viewing changes to doc/developers/HACKING.txt

  • Committer: Martin Pool
  • Date: 2008-04-23 01:46:46 UTC
  • mto: This revision was merged to the branch mainline in revision 3415.
  • Revision ID: mbp@sourcefrog.net-20080423014646-iz0bxhiue6fnxdni
Updated info about assertions

Show diffs side-by-side

added added

removed removed

Lines of Context:
doc/developers/HACKING.txt
680
680
  if getattr(thing, 'name', None) is None
681
681
 
682
682
 
683
 
Assertions
684
 
----------
685
 
 
686
 
Do not use the Python ``assert`` statement, either in tests or elsewhere.
687
 
A source test checks that it is not used.
688
 
 
689
 
 * It makes the behaviour vary depending on whether bzr is run with -O
690
 
   or not, therefore giving a chance for bugs that occur in one case or
691
 
   the other, several of which have already occurred: assertions with
692
 
   side effects, code which can't continue unless the assertion passes,
693
 
   cases where we should give the user a proper message rather than an
694
 
   assertion failure.
695
 
 * It's not that much shorter than an explicit if/raise.
696
 
 * It tends to lead to fuzzy thinking about whether the check is
697
 
   actually needed or not, and whether it's an internal error or not
698
 
 * It tends to cause look-before-you-leap patterns.
699
 
 * It's unsafe if the check is needed to protect the integrity of the
700
 
   user's data.
701
 
 * It tends to give poor messages since the developer can get by with
702
 
   no explanatory text at all.
703
 
 * We can't rely on people always running with -O in normal use, so we
704
 
   can't use it for tests that are actually expensive.
705
 
 * Expensive checks that help developers are better turned on from the
706
 
   test suite or a -D flag.
707
 
 * If used instead of ``self.assert*()`` in tests it makes them falsely pass with -O.
708
 
 
709
 
 
710
683
Code layout
711
684
-----------
712
685
 
1201
1174
final fullstop.  If long, they may contain newlines to break the text.
1202
1175
 
1203
1176
 
 
1177
Assertions
 
1178
----------
 
1179
 
 
1180
Do not use the Python ``assert`` statement, either in tests or elsewhere.
 
1181
A source test checks that it is not used.  It is ok to explicitly raise
 
1182
AssertionError.
 
1183
 
 
1184
Rationale:
 
1185
 
 
1186
 * It makes the behaviour vary depending on whether bzr is run with -O
 
1187
   or not, therefore giving a chance for bugs that occur in one case or
 
1188
   the other, several of which have already occurred: assertions with
 
1189
   side effects, code which can't continue unless the assertion passes,
 
1190
   cases where we should give the user a proper message rather than an
 
1191
   assertion failure.
 
1192
 * It's not that much shorter than an explicit if/raise.
 
1193
 * It tends to lead to fuzzy thinking about whether the check is
 
1194
   actually needed or not, and whether it's an internal error or not
 
1195
 * It tends to cause look-before-you-leap patterns.
 
1196
 * It's unsafe if the check is needed to protect the integrity of the
 
1197
   user's data.
 
1198
 * It tends to give poor messages since the developer can get by with
 
1199
   no explanatory text at all.
 
1200
 * We can't rely on people always running with -O in normal use, so we
 
1201
   can't use it for tests that are actually expensive.
 
1202
 * Expensive checks that help developers are better turned on from the
 
1203
   test suite or a -D flag.
 
1204
 * If used instead of ``self.assert*()`` in tests it makes them falsely pass with -O.
 
1205
 
 
1206
 
1204
1207
Documenting Changes
1205
1208
===================
1206
1209