add CODESTYLE to document programming style/conventions

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

2 files changed, 179 insertions, 17 deletions

diff --git a/src/CODESTYLE b/src/CODESTYLE
new file mode 100644
index 0000000..ed92163
--- /dev/null
+++ b/src/CODESTYLE
@@ -0,0 +1,155 @@
+AHFinderDirect Code Style
+=========================
+$Header: /usr/local/svn/cvs-repositories/numrelcvs/AEIThorns/AHFinderDirect/src/CODESTYLE,v 1.1 2003-03-22 18:56:49 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
+
+At least as of version 7, Maple doesn't have a usable preprocessor,
+so I've written my own (src/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)
+
+
+Only a few options are configured at compile-time; these use #defines
+in src/include/config.h.
+
+
+Code Layout/Indentation
+========================
+
+Most comments are C++-style //-to-end-of-line comments.  In C files,
+or in header files which have to be C-compatible, I use C-style
+/* comments */.
+
+I like to make the two branches of an if-else statement look symmetrical:
+so I use
+  #define then   /* empty */
+with usage as shown below.
+
+A lot of the code uses the generic floating-point data type
+  typedef CCTK_REAL fp;
+
+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
+
+... surrounding code
+	while (condition)
+	{
+	... body of while loop
+	}
+
+
+All switch statements should have a  default:  case (which often just
+does an  error_exit()).
+
+... surrounding code
+switch	(expression)
+	{
+case 42:
+	... code for this case
+	break;
+case 69:
+	... code for this case
+	break;
+case 105:
+	... code for this case
+	break;
+default:
+	... code for this case
+	break;
+	}
+
+//
+// block comment describing function
+//
+int foo(fp x, int bar, int baz)
+{
+... 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
+should be const-correct.
+
+Most casts are new-style  const_cast<...>(...)  or  static_cast<...>(...) .
+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
+  }
+
+
+Error Handling
+==============
+
+For historical reasons, the code uses two slightly different mechanisms
+for "print an error message and abort the Cactus run" error handling:
+* Lower-level code (in src/{jtutil,patch,gr,elliptic}/) uses error_exit()
+  (defined in src/include/stdc.h):
+	if (user input was very bad)
+	   then error_exit(ERROR_EXIT,
+"***** function_name(): user input was really bad\n"
+"                       printf(3)-style string and following arguments\n"
+"                       to describe what went wrong"
+			   ,
+			   foo, var, double(baz));		/*NOTREACHED*/
+  Here the first argument is ERROR_EXIT for "bad user input" errors,
+  or PANIC_EXIT for "this should never happen" failure of internal
+  consistency checks.  For this thorn, error_exit() is implemented as
+  a call to...
+* Higher-level code (in src/{driver,elliptic,gr}) uses the standard
+  Cactus CCTK_VWarn(), generally giving FATAL_ERROR (defined in
+  src/include/config.h) as the warning level.
+
+
+C++ Classes and Libraries
+=========================
+
+All the main data structures are C++ classes, but there are also plenty
+of C-style structs.  struct foo  is for "dumb data", and has at most
+contructors.  class foo  is for full-fledged C++ classes; these have
+no public data members.  C++ class data members have names with a
+trailing underscore; no other identifiers in this thorn have such names.
+
+Most "large" classes are non-copyable and non-assignable.  Right now
+I write this explicitly in each class; once compilers improve a bit more
+and boost becomes more widely deployed it would be cleaner to convert this
+to inheriting from boost::noncopyable.
+
+In the same genre, once compilers imprive a *lot* more :), most/all
+of the raw new[]-array references should probably be converted to
+boost::array, and my jtutil::array[1234]d<> classes should be converted
+to boost::multi_array.
+
+
+Miscellaneous
+=============
+
+All I/O is done using C stdio (printf() and friends); the C++ iostreams
+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...
diff --git a/src/README b/src/README
index b6cafd0..b2f73f3 100644
--- a/src/README
+++ b/src/README
@@ -1,24 +1,31 @@
 This is the top-level source directory for the AHFinderDirect thorn.
 See ../doc/ for further documentation.
 
-The main subdirectories under this directory are:
-driver/		high-level driver routines to solve the Theta(h) = 0
-		equations and interface to the rest of Cactus
-elliptic/	code to solve elliptic equations on the multipatch $S^2$
-gr/		relativity code; all knowledge of the actual apparent
-		horizon equation lives in the code in this directory
-gr.cg/		Maple-generated code to compute the Theta(h) function
-		and its Jacobian coefficients
-patch/		basic multipatch infrastructure for storing and
-		finite differencing gridfns in angular coordinates
+In this directory,
+CODESTYLE	documents some general programming conventions I have
+		used in this thorn
+driver/		contains high-level driver routines to solve the
+		Theta(h) = 0 equations and interface to the rest of Cactus
+elliptic/	contains code to solve elliptic equations on the multipatch
+		$S^2$
+gr/		contains relativity code; all knowledge of the actual
+		apparent horizon equation lives in the code in this directory
+gr.cg/		contains Maple-generated code to compute the Theta(h)
+		function and its Jacobian coefficients
+patch/		contains the basic multipatch infrastructure for storing
+		and finite differencing gridfns in angular coordinates
 		on the surface of a 2-sphere
-jtutil/		low-level utility library in C++ namespace jtutil::
+jtutil/		contains various low-level utility routines
 		(templates and inline functions for things like
 		integer <--> floating-point linear maps, fuzzy
-		floating-point comparisons, N-dimensional arrays, etc)
-include/	common header files which don't live in any other
+		floating-point comparisons, N-dimensional arrays, etc);
+		except for one C function which will disappear once
+		Tom Goodale commits some pending Cactus-flesh changes)
+		all this code lives in the C++ namespace jtutil::
+include/	contains common header files which don't live in any other
 		source directory
-misc/		misc source code that doesn't fit anywhere else,
-		including the 'mpp' Maple preprocessor used by the
-		Maple code in other directories
-maple/		Maple code to generate C/C++ from complicated expressions
+misc/		contains misc source code that doesn't fit anywhere else,
+		including the 'mpp' Maple preprocessor used by the Maple
+		code in other directories
+maple/		contains Maple code to generate C/C++ from complicated
+		expressions