Changes between Version 16 and Version 17 of CodingStandards

Timestamp:

2011-09-26T22:44:01Z (13 years ago)

Author:

davidsarah

Comment:

move "assertion policy" section to a more relevant place

CodingStandards

@@ -97 +97 @@
 Now you can put {{{assert self._assert_invariants()}}} 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.
 
-* we actually appear to only have one instance of this pattern in Tahoe at time of writing, in {{{allmydata.util.dictutil}}}. It has the disadvantage of cluttering up the logic with calls to {{{_assert_invariants}}}, and should probably be used sparingly. -- DavidSarah
+* we actually appear to only have one instance of this pattern in Tahoe at time of writing, in {{{allmydata.util.dictutil}}}. It has the disadvantage of cluttering up the logic with calls to {{{_assert_invariants}}}, and should probably be used sparingly. -- David-Sarah
+
+==== assertion policy ====
+
+One axis of interest is how time-consuming the checks are. Many precondition
+checks can cause typical runtime to explode to O(n^2^) or O(n^3^), for example
+{{{SortedList.__contains__}}} called {{{_assert_invariants}}} which took
+O(n log n) each time, when {{{__contains__}}} ought to be O(log n). A caller who
+was expecting {{{if b in list}}} to take O(log n) could easily wind up turning
+their O(n log n) routine into O(n^2^) or worse.
+
+Another axis is "who could cause it to fail": some checks are looking only at
+internal state. For example, if {{{SortedList._assert_invariants}}} fails, it
+indicates a problem in some {{{SortedList}}} method. Other checks are
+enforcing the external API, like those which do typechecks on input
+arguments. Even after the {{{SortedList}}} developer has gained confidence in
+the code and decides that internal checks are no longer necessary, it may be
+useful to retain the external checks to isolate usage problems that exist in
+callers.
+
+ * The general rule is that nodes must be functional for light traffic even
+   when the assertions are turned on. When assertions are turned off (-O),
+   nodes must be functional for heavy traffic.
+
+ * Time-consuming internal checks: once the code is working properly,
+   consider removing them, but they may be left in place as long as they
+   use {{{assert}}} (the form which gets turned off when -O is used).
+
+ * Cheap internal checks: once the code is working properly, consider
+   removing them, but it is less of a concern than the time-consuming ones.
+   If they really are cheap, use {{{_assert}}} (the unconditional form
+   that gets used even with -O).
+
+ * Time-consuming external checks: maybe leave them in place, but always
+   use {{{assert}}} so they will not be used with -O.
+
+ * Cheap external checks: leave them in place, using the unconditional
+   {{{_assert}}}
+
+ * Production grids could run with -O (in practice, the allmydata.com production grid runs without -O, because there are no expensive checks in the current codebase).
+
+ * Testing grids might run without -O in order to detect more bugs.
+
+ * Local developer tests will probably not use -O, and developers should be
+   prepared to experience the same CPU load problems if they subject their
+   nodes to real traffic levels. Developers can use -O to turn off everyone
+   else's checks, use {{{_assert}}} on their own code to enable their own
+   assertions, and then subject their nodes to heavy traffic, as long as they
+   are sure to change their checks to use {{{assert}}} (or remove them
+   altogether) before committing.
+
 
 === configuration ===
@@ -135 +185 @@
 
 
-==== assertion policy ====
-
-One axis of interest is how time-consuming the checks are. Many precondition
-checks can cause typical runtime to explode to O(n^2^) or O(n^3^), for example
-{{{SortedList.__contains__}}} called {{{_assert_invariants}}} which took
-O(n log n) each time, when {{{__contains__}}} ought to be O(log n). A caller who
-was expecting {{{if b in list}}} to take O(log n) could easily wind up turning
-their O(n log n) routine into O(n^2^) or worse.
-
-Another axis is "who could cause it to fail": some checks are looking only at
-internal state. For example, if {{{SortedList._assert_invariants}}} fails, it
-indicates a problem in some {{{SortedList}}} method. Other checks are
-enforcing the external API, like those which do typechecks on input
-arguments. Even after the {{{SortedList}}} developer has gained confidence in
-the code and decides that internal checks are no longer necessary, it may be
-useful to retain the external checks to isolate usage problems that exist in
-callers.
-
- * The general rule is that nodes must be functional for light traffic even
-   when the assertions are turned on. When assertions are turned off (-O),
-   nodes must be functional for heavy traffic.
-
- * Time-consuming internal checks: once the code is working properly,
-   consider removing them, but they may be left in place as long as they
-   use {{{assert}}} (the form which gets turned off when -O is used).
-
- * Cheap internal checks: once the code is working properly, consider
-   removing them, but it is less of a concern than the time-consuming ones.
-   If they really are cheap, use {{{_assert}}} (the unconditional form
-   that gets used even with -O).
-
- * Time-consuming external checks: maybe leave them in place, but always
-   use {{{assert}}} so they will not be used with -O.
-
- * Cheap external checks: leave them in place, using the unconditional
-   {{{_assert}}}
-
- * Production grids could run with -O (in practice, the allmydata.com production grid runs without -O, because there are no expensive checks in the current codebase).
-
- * Testing grids might run without -O in order to detect more bugs.
-
- * Local developer tests will probably not use -O, and developers should be
-   prepared to experience the same CPU load problems if they subject their
-   nodes to real traffic levels. Developers can use -O to turn off everyone
-   else's checks, use {{{_assert}}} on their own code to enable their own
-   assertions, and then subject their nodes to heavy traffic, as long as they
-   are sure to change their checks to use {{{assert}}} (or remove them
-   altogether) before committing.
-
-
 == official Python standards ==