Changeset 51d7f7b in git

Timestamp:

Jun 5, 2009, 4:34:06 AM (14 years ago)

Author:

Motsak Oleksandr <motsak@…>

Branches:

(u'spielwiese', '0d6b7fcd9813a1ca1ed4220cfa2b104b97a0a003')

Children:

6dccbc5e8c728811407cb76468333f90ed59ee31

Parents:

01e88747d8875ada5e3d5eee6e8ef8a6a5509822

Message:

*motsak: some more


git-svn-id: file:///usr/local/Singular/svn/trunk@11879 2c84dea3-7e68-4137-9b89-c4e89433aadc

File:

• doc/C-STYLEGUIDE (modified) (5 diffs)

doc/C-STYLEGUIDE

@@ -1 +1 @@
 C/C++-Style guide for Singular
 -----------------------------
-- Header files
-  - each header file abc.h should start with
-    #ifndef ABC_H
-    #define ABC_H
-    and end with
-    #endif
-  - include only the header files you really need
-  - do nor include mod2.h
-
-- C/C++ files - names
+- 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
@@ -20 +11 @@
 
 - C/C++ files - structure
-  - each C/C++ file (abc.c/abc.cc) should start with a short comment
-    about its purpose
-  - include first all system include files
-  - include mod2.h
-  - include all other files (which you really need)
+  - TODO: What about Copyright note?
+  - 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. 
+    TODO: should not contain CVS $Id: C-STYLEGUIDE,v 1.4 2009-06-05 02:34:06 motsak Exp $ tag!?
+  - order "#include" statements from global to local scope:
+      i. first: all system include files: 
+        #include <iostream>, #include <boost/shred_ptr.h>
+     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 for each level of nesting)
+    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)
+  - compiler warnings should be enabled and regarded as errors
+  - whenever possible, constants should be defined as "const variables" 
+    not via "#define" 
+  - macroses should be avoided. Use "inline" functions instead
+
 
 - Naming conventions:
@@ -53 +87 @@
 
 - Comments
-  - each procedure should documents its input/output/side effects
-    (-> automatic build of programmers manual)
-  - do not comment on trivial matters
+  - 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
+  - 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.
@@ -69 +113 @@
   - more time consuming tests should be within
     #ifdef PDEBUG/#ifdef KDEBUG/#ifdef LDEBUG
-   (see mod2.h)
+    (see mod2.h)
   - case statements (or equivalent if/else constructs)
     should always have an default entry
@@ -78 +122 @@
     if you really need C++ extensions, use "class".
   - "and"/"or"/"not" are not recognized by all compilers, use &&, &, ||, |, !
+  - TODO: What about namespaces!?
+