C/C++-Style guide for Singular ----------------------------- - C/C++ files - names (applies to headers as well) - each C++ file should have the extension .cc - each C file should have the extension .c - each header file should have the extension .h it should be possible to include it in C and C++ sources - converted to lower case, each file name must be unique in the first 8 characters - it is recommended to use only lower case file names - C/C++ files - structure - TODO: What about Copyright note? (Contained in COPYING unless otherwise specified). - each C/C++ file (abc.c/abc.cc/abc.h) should start with a short comment about its purpose in doxygen format (TODO: see file templates) giving at least the filename and a brief description of the contents. (Each header of a file should contain an Id/Rev field) - order "#include" statements from global to local scope: i. first: all system include files: #include , #include (remember to include optional include files in #ifdef ... #end) ii. only source files: #include "mod2.h" iii. at last: all other files (which you really need): #include "poly.h" etc. - paths in "#include" statements should be avoided (should be specified by build system level instead) - Header files - see C/C++ files - structure! - each header file abc.h should contain a multiple inclusions preventing mechanism as follows: #ifndef ABC_H #define ABC_H // .... declarations ... #endif // ABC_H - do NOT include mod2.h! - include only the header files you really need (use forward declarations wherever possible) - all declarations (macros, types, variables, enumerations, function parameters...) should be documented in doxygen format. Brief comments are mandatory, long comments are optional (TODO: see file templates) - class-/function-/member variable-/... comments should be written in the doxygen format (see Doxygen quick reference card) - further (non doxygen) comments can be used to separate the file into easily visible sections - format - general screen width: 80 columns - each procedure declarations should be in one line, if possible - the number of required function parameters should be as small as possible - curly braces: Matching curly brackets should be either vertically or horizontally aligned. - the "else" keyword indents the same as its matching "if" - indentation should be small (e.g. two positions (spaces) for each level of nesting) - avoid tabs: their interpretation differs from editor to editor. - use empty lines seldom: only to break up very long routines and between routines - avoid code copying/duplication - declare local variables as late as possible and with the smallest possible visibility scope - avoid using "goto", "continue", "break" statements (save for "switch/case" blocks and error handling) - compiler warnings should be enabled and regarded as errors - whenever possible, constants should be defined as "const variables" not via "#define". Non pure C++ parts must use #define. - Consider the choice between macros and inline function very careful, prefer inline functions: - macros are not type safe + macros are allways inlined - arguments to macros can be multiply computed - "inline" is only a hint for the optimizer (especially in the C parts): in non-optimzed code these functions are NOT inlined. -/+ inline functions are not generic (requires the defined types) - Naming conventions: - All code and global variables must conform to this naming convention, it does not apply to local variables. - the names consists of a short (small letter) prefix, the first letter of each following word is capitalized (The routines Werror/WerrorS/Warn/WarnS/Print/PrintS have an empty prefix) - the prefix describes the area the name belongs to: p: polynomial operations n/np/nl/na/: number operations (general/Zp/Q/alg.ext.) k: std engine ... - _ (underscore) is only used as a last part of the prefix: (example: p_Add): the last argument is the base ring - macros are in capital letters (except used as a procedure) - Comments - class-/function-/member variable-/... comments should be written in the doxygen format (see Doxygen quick reference card) - documentation should explain the purpose of each type/function/parameter/., as well as its return value or any preconditions/side effects if applicable - comments in source files about implementation details need not be in doxygen format - do not comment on trivial matters. Implementation details should be sufficiently commented for others to understand the inner workings of the code. - document difficult algorithms by a reference to an article/book/etc. - Checks / Debugging aids - interpreter routines have to check their input - use const wherever possible/suitable (especially in declarations of input parameters to functions/methods provided as pointers or references or for methods that do not change the state of an object, consider delaring variables "mutable" whenever suitable) - kernel routines have to document their requirements, the checks have to be done in the interpreter. Repeat the checks only within #ifndef NDEBUG/#endif or via assert. - input should be checked to conform with the documentation via assume (if this is simple) - more time consuming tests should be within #ifdef PDEBUG/#ifdef KDEBUG/#ifdef LDEBUG (see mod2.h) - case statements (or equivalent if/else constructs) should always have an default entry (maybe an error message) - C++ features - to avoid confusion: "struct" should be a C object, if you really need C++ extensions, use "class". - "and"/"or"/"not" are not recognized by all compilers, use &&, &, ||, |, !