X-Git-Url: http://git.megacz.com/?p=ghc-hetmet.git;a=blobdiff_plain;f=docs%2Fcoding-style.html;h=ceca6b9babec64da02a610dbd85c29372756d8d1;hp=ba935092ba32b7a8fb97687d25d988517c14c0b6;hb=3cdceb2d3ec67d8f96528f4cbc0a16a06b2f7fe4;hpb=af1b1d936747762b8faeb9f852cb9f58cdd58bea
diff --git a/docs/coding-style.html b/docs/coding-style.html
index ba93509..ceca6b9 100644
--- a/docs/coding-style.html
+++ b/docs/coding-style.html
@@ -191,6 +191,16 @@ an int to a nat, add an assertion. If you're casting an int to a char,
add an assertion.
+Write special debugging code to check the integrity of your data structures.
+(Most of the runtime checking code is in src/Sanity.c)
+Add extra assertions which call this code at the start and end of any
+code that operates on your data structures.
+
+
+When you find a hard-to-spot bug, try to think of some assertions,
+sanity checks or whatever that would have made the bug easier to find.
+
+
When defining an enumeration, it's a good idea not to use 0 for normal
values. Instead, make 0 raise an internal error. The idea here is to
make it easier to detect pointer-related errors on the assumption that
@@ -204,7 +214,14 @@ typedef enum
...
+
Use #warning or #error whenever you write a piece of incomplete/broken code.
+
+ When testing, try to make infrequent things happen often.
+ For example, make a context switch/gc/etc happen every time a
+ context switch/gc/etc can happen. The system will run like a
+ pig but it'll catch a lot of bugs.
+
Syntactic details
@@ -315,6 +332,10 @@ of side effects, evaluation order, multiple evaluation, etc.
Inline functions have call-by-value semantics whereas macros
are call-by-name. You can be bitten by duplicated computation
if you aren't careful.
+
+ You can use inline functions from inside gdb if you compile with
+ -O0 or -fkeep-inline-functions. If you use macros, you'd better
+ know what they expand to.
However, note that macros can serve as both l-values and r-values and
@@ -379,10 +400,31 @@ in the library.
-Try to use ANSI C's enum feature when defining lists of constants of the
-same type. You'll notice that gdb works better when you do this.
-For example:
+This code
+
+int* p, q;
+
+looks like it declares two pointers but, in fact, only p is a pointer.
+It's safer to write this:
+
+int* p;
+int* q;
+
+You could also write this:
+
+int *p, *q;
+
+but Alastair prefers to split the declarations.
+
+
+Try to use ANSI C's enum feature when defining lists of constants of
+the same type. Among other benefits, you'll notice that gdb uses the
+name instead of its (usually inscrutable) number when printing values
+with enum types and gdb will let you use the name in expressions you
+type.
+
+Examples:
typedef enum { /* N.B. Used as indexes into arrays */
NO_HEAP_PROFILING,