Expand declaration QQs first (#10047)
[ghc.git] / docs / coding-style.html
index 250ab88..6be9263 100644 (file)
@@ -1,11 +1,12 @@
-<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 3.2//EN">
-<HTML>
-<HEAD>
-   <TITLE>GHC Style Guidelines for C code</TITLE>
-</HEAD>
-<BODY>
+<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN" "http://www.w3.org/TR/html4/loose.dtd">
+<html>
+<head>
+   <meta http-equiv="content-type" content="text/html;charset=iso-8859-1">
+   <title>Style Guidelines for fptools</title>
+</head>
+<body>
 
-<H1>GHC Style guidelines for C code</h1>
+<h1>Style Guidelines for fptools</h1>
 
 <h2>Comments</h2>
 
@@ -35,7 +36,7 @@ the only Microsoft Press book that's worth reading.)
 
 <p><li>
 Autoconf documentation.
-See also <a href="http://peti.gmd.de/autoconf-archive/">The autoconf macro archive</a> and 
+See also <a href="http://peti.gmd.de/autoconf-archive/">The autoconf macro archive</a> and
 <a href="http://www.cyclic.com/cyclic-pages/autoconf.html">Cyclic Software's description</a>
 
 <p><li> <a
@@ -57,12 +58,12 @@ Hill C Style and Coding Standards</a>.
 <h2>Portability issues</h2>
 
 <ul>
-<p><li> We try to stick to C99 where possible.  We use the following
+<li> We try to stick to C99 where possible.  We use the following
 C99 features relative to C89, some of which were previously GCC
 extensions (possibly with different syntax):
 
 <ul>
-<p><li>Variable length arrays as the last field of a struct.  GCC has
+<li>Variable length arrays as the last field of a struct.  GCC has
 a similar extension, but the syntax is slightly different: in GCC you
 would declare the array as <tt>arr[0]</tt>, whereas in C99 it is
 declared as <tt>arr[]</tt>.
@@ -90,9 +91,9 @@ header file).
 <tt>#ifdef __GNUC__</tt>:
 
 <ul>
-<p><li>Function attributes (mostly just <code>no_return</code> and
+<li>Function attributes (mostly just <code>no_return</code> and
 <code>unused</code>)
-<p><li>Inline assembly.
+<li>Inline assembly.
 </ul>
 
 <p><li>
@@ -164,8 +165,8 @@ Avoid conditional code like this:
   #endif
 </pre>
 
-Instead, add an appropriate test to the configure.in script and use
-the result of that test instead. 
+Instead, add an appropriate test to the configure.ac script and use
+the result of that test instead.
 
 <pre>
   #ifdef HAVE_BSD_H
@@ -223,24 +224,24 @@ code is removed altogether if <tt>DEBUG</tt> is not defined).
 Particular guidelines for writing robust code:
 
 <ul>
-<p><li>
+<li>
 Use assertions.  Use lots of assertions.  If you write a comment
 that says "takes a +ve number" add an assertion.  If you're casting
 an int to a nat, add an assertion.  If you're casting an int to a char,
 add an assertion.  We use the <tt>ASSERT</tt> macro for writing
 assertions; it goes away when <tt>DEBUG</tt> is not defined.
 
-<p><li>
+<li>
 Write special debugging code to check the integrity of your data structures.
 (Most of the runtime checking code is in <tt>rts/Sanity.c</tt>)
 Add extra assertions which call this code at the start and end of any
 code that operates on your data structures.
 
-<p><li>
+<li>
 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.
 
-<p><li>
+<li>
 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
@@ -259,8 +260,8 @@ typedef enum
 piece of incomplete/broken code.
 
 <p><li> 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 
+     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.
 
 </ul>
@@ -268,7 +269,7 @@ piece of incomplete/broken code.
 <h2>Syntactic details</h2>
 
 <ul>
-<p><li><b>Important:</b> Put "redundant" braces or parens in your code.
+<li><b>Important:</b> Put "redundant" braces or parens in your code.
 Omitting braces and parens leads to very hard to spot bugs -
 especially if you use macros (and you might have noticed that GHC does
 this a lot!)
@@ -276,13 +277,13 @@ this a lot!)
 <p>
 In particular:
 <ul>
-<p><li>
+<li>
 Put braces round the body of for loops, while loops, if statements, etc.
 even if they "aren't needed" because it's really hard to find the resulting
 bug if you mess up.  Indent them any way you like but put them in there!
 </ul>
 
-<p><li>
+<li>
 When defining a macro, always put parens round args - just in case.
 For example, write:
 <pre>
@@ -293,25 +294,25 @@ instead of
   #define add(x,y) x+y
 </pre>
 
-<p><li> Don't declare and initialize variables at the same time.
+<li> Don't declare and initialize variables at the same time.
 Separating the declaration and initialization takes more lines, but
 make the code clearer.
 
-<p><li>
+<li>
 Use inline functions instead of macros if possible - they're a lot
 less tricky to get right and don't suffer from the usual problems
 of side effects, evaluation order, multiple evaluation, etc.
 
 <ul>
-<p><li>Inline functions get the naming issue right.  E.g. they
+<li>Inline functions get the naming issue right.  E.g. they
   can have local variables which (in an expression context)
   macros can't.
 
-<p><li> Inline functions have call-by-value semantics whereas macros
+<li> 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.
 
-<p><li> You can use inline functions from inside gdb if you compile with
+<li> 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.
 </ul>
@@ -323,18 +324,18 @@ can be "polymorphic" as these examples show:
   #define PROF_INFO(cl) (((StgClosure*)(cl))->header.profInfo)
 
   // polymorphic case
-  // but note that min(min(1,2),3) does 3 comparisions instead of 2!!
+  // but note that min(min(1,2),3) does 3 comparisons instead of 2!!
   #define min(x,y) (((x)<=(y)) ? (x) : (y))
 </pre>
 
-<p><li>
+<li>
 Inline functions should be "static inline" because:
 <ul>
-<p><li>
+<li>
 gcc will delete static inlines if not used or theyre always inlined.
 
-<p><li>
-  if they're externed, we could get conflicts between 2 copies of the 
+<li>
+  if they're externed, we could get conflicts between 2 copies of the
   same function if, for some reason, gcc is unable to delete them.
   If they're static, we still get multiple copies but at least they don't conflict.
 </ul>
@@ -378,7 +379,7 @@ in the library.
 </pre>
 
 <p><li>
-Don't define macros that expand to a list of statements.  
+Don't define macros that expand to a list of statements.
 You could just use braces as in:
 
 <pre>
@@ -392,14 +393,13 @@ You could just use braces as in:
 (but it's usually better to use an inline function instead - see above).
 
 <p><li>
-Don't even write macros that expand to 0 statements - they can mess you 
+Don't even write macros that expand to 0 statements - they can mess you
 up as well.  Use the doNothing macro instead.
 <pre>
   #define doNothing() do { } while (0)
 </pre>
-</ul>
 
-<p><li>
+<li>
 This code
 <pre>
 int* p, q;
@@ -416,37 +416,37 @@ int *p, *q;
 </pre>
 but it is preferrable to split the declarations.
 
-<p><li>
+<li>
 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.  
+type.
 
 <p>
 Examples:
 <pre>
     typedef enum { /* N.B. Used as indexes into arrays */
-     NO_HEAP_PROFILING,                
-     HEAP_BY_CC,               
-     HEAP_BY_MOD,              
-     HEAP_BY_GRP,              
-     HEAP_BY_DESCR,            
-     HEAP_BY_TYPE,             
-     HEAP_BY_TIME              
+     NO_HEAP_PROFILING,
+     HEAP_BY_CC,
+     HEAP_BY_MOD,
+     HEAP_BY_GRP,
+     HEAP_BY_DESCR,
+     HEAP_BY_TYPE,
+     HEAP_BY_TIME
     } ProfilingFlags;
 </pre>
 instead of
 <pre>
-    # define NO_HEAP_PROFILING 0       /* N.B. Used as indexes into arrays */
-    # define HEAP_BY_CC                1
-    # define HEAP_BY_MOD       2
-    # define HEAP_BY_GRP       3
-    # define HEAP_BY_DESCR     4
-    # define HEAP_BY_TYPE      5
-    # define HEAP_BY_TIME      6
+    # define NO_HEAP_PROFILING 0 /* N.B. Used as indexes into arrays */
+    # define HEAP_BY_CC        1
+    # define HEAP_BY_MOD       2
+    # define HEAP_BY_GRP       3
+    # define HEAP_BY_DESCR     4
+    # define HEAP_BY_TYPE      5
+    # define HEAP_BY_TIME      6
 </pre>
-and 
+and
 <pre>
     typedef enum {
      CCchar    = 'C',
@@ -467,16 +467,16 @@ instead of
     # define TIMEchar  'T'
 </pre>
 
-<p><li> Please keep to 80 columns: the line has to be drawn somewhere,
+<li> Please keep to 80 columns: the line has to be drawn somewhere,
 and by keeping it to 80 columns we can ensure that code looks OK on
 everyone's screen.  Long lines are hard to read, and a sign that the
 code needs to be restructured anyway.
 
-<p><li> When commenting out large chunks of code, use <code>#ifdef 0
+<li> When commenting out large chunks of code, use <code>#ifdef 0
 ... #endif</code> rather than <code>/* ... */</code> because C doesn't
 have nested comments.
 
-<p><li>When declaring a typedef for a struct, give the struct a name
+<li>When declaring a typedef for a struct, give the struct a name
 as well, so that other headers can forward-reference the struct name
 and it becomes possible to have opaque pointers to the struct.  Our
 convention is to name the struct the same as the typedef, but add a
@@ -488,10 +488,10 @@ leading underscore.  For example:
   } Foo;
 </pre>
 
-<p><li>Do not use <tt>!</tt> instead of explicit comparison against
+<li>Do not use <tt>!</tt> instead of explicit comparison against
 <tt>NULL</tt> or <tt>'\0'</tt>;  the latter is much clearer.
 
-<p><li> We don't care too much about your indentation style but, if
+<li> We don't care too much about your indentation style but, if
 you're modifying a function, please try to use the same style as the
 rest of the function (or file).  If you're writing new code, a
 tab width of 4 is preferred.
@@ -501,7 +501,7 @@ tab width of 4 is preferred.
 <h2>CVS issues</h2>
 
 <ul>
-<p><li>
+<li>
 Don't be tempted to reindent or reorganise large chunks of code - it
 generates large diffs in which it's hard to see whether anything else
 was changed.
@@ -512,5 +512,31 @@ it in case anyone else is changing that file.
 </ul>
 
 
+<h2>Commandline arguments</h2>
+
+A program in fptools should try follow the following rules for
+commandline arguments:
+
+<ul>
+<li> The <code>-v</code> and <code>--verbose</code> options should be
+used to generate verbose output (intended for the user).
+
+<li> The <code>-d</code> and <code>--debug</code> options should be
+used to generate debugging output (intended for the developer).
+
+<li> The <code>-?</code> and <code>--help</code> options should be used
+to display usage information on stdout. The program should exit
+successfully afterwards.
+
+<li> The <code>-V</code> and <code>--version</code> options should be
+used to output version information on stdout, which includes one line
+of the form '<code><em>Program</em> version
+<em>Major.Minor[.Patchlevel]</em> ... </code>'.  The program
+should exit successfully afterwards.
+</ul>
+
+When an unknown commandline argument is encountered, the program
+should display usage information on stderr and exit unsuccessfully.
+
 </body>
 </html>