further explanations of this thorn's programming style

git-svn-id: http://svn.einsteintoolkit.org/cactus/EinsteinAnalysis/AHFinderDirect/trunk@1107 f88db872-0e4f-0410-b76b-b9085cfa78c5

1 files changed, 68 insertions, 37 deletions

diff --git a/src/CODESTYLE b/src/CODESTYLE
index 10488a3..4e7439b 100644
--- a/src/CODESTYLE
+++ b/src/CODESTYLE
@@ -1,25 +1,27 @@
 AHFinderDirect Code Style
 =========================
-$Header: /usr/local/svn/cvs-repositories/numrelcvs/AEIThorns/AHFinderDirect/src/CODESTYLE,v 1.3 2003-06-02 20:15:20 jthorn Exp $
+$Header: /usr/local/svn/cvs-repositories/numrelcvs/AEIThorns/AHFinderDirect/src/CODESTYLE,v 1.4 2003-06-23 19:38:34 jthorn Exp $
 
 This file documents some general programming conventions used in this
 thorn.
 
 File Naming
 ===========
-*.c, *.h	C code, headers		*.c, *.h
-*.cc, *.hh	C++ code, headers	*.cc, *.hh
+*.c, *.h	C code, headers
+*.cc, *.hh	C++ code, headers
 
 At least as of version 7, Maple doesn't have a usable preprocessor,
-so I've written my own (src/mpp).
+so I've written my own (in Perl); it lives in misc/mpp.
 
 *.maple		Maple code (input to my Maple preprocessor)
 *.minc		Maple headers to be @included by my Maple preprocessor
 *.mm		Maple code (output from my Maple preprocessr)
 
 None of my header files ever #includes another file, so in theory there's
-no problem with multiple inclusion.  However, see "C++ Templates" below
-for some ugly compiler problems with this...
+no problem with multiple inclusion.  However, to work around C++ compiler
+problems, some header files are still explicitly protected against multiple
+inclusion with the standard #ifndef trick; see "C++ Templates" below for
+details.
 
 
 Configuration
@@ -46,44 +48,59 @@ A lot of the code uses the generic floating-point data type
 
 Almost (but not quite) all the code fits into 80 columns.
 
-The indentation style is typified by the following examples.  Roughly
-speaking, indentation depth reflects execution frequency.  Normal
-indentation is 1 tab stop = 8 spaces.  Sometimes a block of code is
-"outdented" back towards the left margin if it's too deeply indented
-to fit easily in an 80-column window.
-
-... surrounding code
-if (condition)
-   then ... if-condition-true code
-   else ... if-condition-false code
+The indentation style is a bit unusual, and is best described by the
+following examples.  Roughly speaking, indentation depth reflects execution
+frequency.  Normal indentation is 1 tab stop = 8 spaces.  Sometimes a
+block of code is "outdented" back towards the left margin if it's too
+deeply indented to fit easily in an 80-column window.
+
+Examples:
+
+<surrounding code>
+if (condition #1)
+   then <if-condition-#1-true code>
+   else <if-condition-#1-false code>
+if (condition #2)
+   then {
+	<if-condition-#2-true code>
+	<if-condition-#2-true code>
+	}
+   else {
+	<if-condition-false code>
+	<if-condition-false code>
+	}
 
-... surrounding code
+<surrounding code>
 	while (condition)
 	{
-	... loop body
+	<loop body>
+	<loop body>
 	}
 
-... surrounding code
+<surrounding code>
 	for (int i = 0 ; i < N ; ++i)
 	{
-	... loop body
+	<loop body>
+	<loop body>
 	}
 
-... surrounding code
 // if there are multiple for-loops in the same scope using the same
 // loop variable, I add extra (redundant) { } around the loops so the
 // code will compile unchanged under both the archaic and the modern
 // for-loop declaration scope rules
+<surrounding code>
 	  {
 	for (int i = 0 ; i < N ; ++i)
 	{
-	... loop #1 body
+	<loop #1 body>
+	<loop #1 body>
 	}
 	  }
 	  {
 	for (int i = 0 ; i < N ; ++i)
 	{
-	... loop #2 body
+	<loop #2 body>
+	<loop #2 body>
 	}
 	  }
 
@@ -91,20 +108,24 @@ if (condition)
 All switch statements should have a  default:  case (which often just
 does an  error_exit()).
 
-... surrounding code
+<surrounding code>
 switch	(expression)
 	{
 case 42:
-	... code for this case
+	<code for this case>
+	<code for this case>
 	break;
 case 69:
-	... code for this case
+	<code for this case>
+	<code for this case>
 	break;
 case 105:
-	... code for this case
+	<code for this case>
+	<code for this case>
 	break;
 default:
-	... code for this case
+	<code for this case>
+	<code for this case>
 	break;
 	}
 
@@ -113,11 +134,12 @@ default:
 //
 int foo(fp x, int bar, int baz)
 {
-... body of function
+<body of function>
+<body of function>
 }
 
 All code should be fully type-secure: there is no aliasing of different
-data types.  const qualifiers are used whereever possible, and all code
+data types.  const qualifiers are used wherever possible, and all code
 should be const-correct.
 
 Most casts are new-style  const_cast<...>(...)  or  static_cast<...>(...) .
@@ -125,10 +147,15 @@ There are no  reinterpret_cast<...>(...)  or  dynamic_cast<...>(...) .
 There are no C-style casts  (type) value .  The only function-style
 casts   type(value)  are to cast numeric datatypes to int/double for
 printf()-style printing, eg
-  void print_x(fp x)
-  {
-  printf("x=%g\n", double(x));    // we don't know if fp is C float or double
-  }
+
+	//
+	// we don't know at compile-time whether the type  fp  is
+	// C float or double
+	//
+	void print_x(fp x)
+	{
+	printf("x=%g\n", double(x));
+	}
 
 
 Error Handling
@@ -153,6 +180,9 @@ for "print an error message and abort the Cactus run" error handling:
   Cactus CCTK_VWarn(), generally giving FATAL_ERROR (defined in
   src/include/config.h) as the warning level.
 
+The code uses the standard Cactus CCTK_VInfo() to print informational
+messages describing what it's doing.
+
 
 C++ Classes and Libraries
 =========================
@@ -185,8 +215,8 @@ I instantiate all templates explicitly.
 
 Some C++ compilers offer "automatic" template instantiation.  In practice
 this often causes compilation to fail when the compiler can't find .cc
-files in other directories.  So, I highly recommend turning *off* all
-automatic template instantiation "features".
+files in other directories, so I highly recommend turning *off* all
+automatic template instantiation "features" when compiling this thorn.
 
 When using the DEC/Compaq/HP/whatever-their-corporate-name-is-this-week
 C++ compiler (version 6.3.6.8) under Alpha Linux, even with automatic
@@ -208,4 +238,5 @@ system isn't used.
 Some Cactus parameter names, and some C++ enumeration and function 
 names, contain the substring "__" (two consecutive underscores).
 According to the C++ standard, such names are reserved to the [compiler]
-implementation.  In practice, so far I haven't had any problems...
+implementation, so this code isn't strictly legal.  In practice, so
+far I haven't had any problems...