diff options
author | jthorn <jthorn@f88db872-0e4f-0410-b76b-b9085cfa78c5> | 2003-03-22 18:56:49 +0000 |
---|---|---|
committer | jthorn <jthorn@f88db872-0e4f-0410-b76b-b9085cfa78c5> | 2003-03-22 18:56:49 +0000 |
commit | b7d9a11348102558aa9ceb9cfd3ce4bd1a185a56 (patch) | |
tree | ef485af16c4a751a7d8a9a8b15a5f54749e8d1ba /src/CODESTYLE | |
parent | 7b1fb49e68d1ab8c409312f37b66cefd0c557152 (diff) |
add CODESTYLE to document programming style/conventions
git-svn-id: http://svn.einsteintoolkit.org/cactus/EinsteinAnalysis/AHFinderDirect/trunk@1003 f88db872-0e4f-0410-b76b-b9085cfa78c5
Diffstat (limited to 'src/CODESTYLE')
-rw-r--r-- | src/CODESTYLE | 155 |
1 files changed, 155 insertions, 0 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... |