source: git/doc/C-STYLEGUIDE @ bb2311

spielwiese
Last change on this file since bb2311 was 99bdcf, checked in by Hans Schoenemann <hannes@…>, 14 years ago
pTotaldegree/p_Totaldegree git-svn-id: file:///usr/local/Singular/svn/trunk@13084 2c84dea3-7e68-4137-9b89-c4e89433aadc
  • Property mode set to 100644
File size: 5.9 KB
Line 
1C/C++-Style guide for Singular
2-----------------------------
3- C/C++ files - names (applies to headers as well)
4  - each C++ file should have the extension .cc
5  - each C file should have the extension .c
6  - each header file should have the extension .h
7    it should be possible to include it in C and C++ sources
8  - converted to lower case, each file name must be unique in the
9    first 8 characters
10  - it is recommended to use only lower case file names
11
12- C/C++ files - structure
13  - TODO: What about Copyright note?
14    (Contained in COPYING unless otherwise specified).
15  - each C/C++ file (abc.c/abc.cc/abc.h) should start with a short comment
16    about its purpose in doxygen format (TODO: see file templates) giving
17    at least the filename and a brief description of the contents.
18    (Each header of a file should contain an Id/Rev field)
19  - order "#include" statements from global to local scope:
20      i. first: all system include files:
21        #include <iostream>, #include <boost/shred_ptr.h>
22       (remember to include optional include files in #ifdef ... #end)
23     ii. only source files: #include "mod2.h"
24    iii. at last: all other files (which you really need):
25        #include "poly.h" etc.
26  - paths in "#include" statements should be avoided (should be specified by
27    build system level instead)
28
29- Header files
30  - see C/C++ files - structure!
31  - each header file abc.h should contain a multiple inclusions preventing
32    mechanism as follows:
33
34    #ifndef ABC_H
35    #define ABC_H
36
37    // .... declarations ...
38
39    #endif // ABC_H
40
41  - do NOT include mod2.h!
42  - include only the header files you really need
43    (use forward declarations wherever possible)
44  - all declarations (macros, types, variables, enumerations, function
45    parameters...) should be documented in doxygen format. Brief comments are
46    mandatory, long comments are optional (TODO: see file templates)
47  - class-/function-/member variable-/... comments should be written in the
48    doxygen format (see Doxygen quick reference card)
49  - further (non doxygen) comments can be used to separate the file into easily
50    visible sections
51
52- format
53  - general screen width: 80 columns
54  - each procedure declarations should be in one line, if possible
55  - the number of required function parameters should be as small as possible
56  - curly braces: Matching curly brackets should be either vertically
57    or horizontally aligned.
58  - the "else" keyword indents the same as its matching "if"
59  - indentation should be small
60    (e.g. two positions (spaces) for each level of nesting)
61  - avoid tabs: their interpretation differs from editor to editor.
62  - use empty lines seldom: only to break up very long routines and between
63    routines
64  - avoid code copying/duplication
65  - declare local variables as late as possible and with the smallest possible
66    visibility scope
67  - avoid using "goto", "continue", "break" statements
68    (save for "switch/case" blocks and error handling)
69  - compiler warnings should be enabled and regarded as errors
70  - whenever possible, constants should be defined as "const variables"
71    not via "#define".
72    Non pure C++ parts must use #define.
73  - Consider the choice between macros and inline function very careful,
74    prefer inline functions:
75    - macros are not type safe
76    + macros are allways inlined
77    - arguments to macros can be multiply computed
78
79    - "inline" is only a hint for the optimizer (especially in the C parts):
80      in non-optimzed code these functions are NOT inlined.
81    -/+ inline functions are not generic (requires the defined types)
82
83- Naming conventions:
84  - All code and global variables must conform to this naming convention,
85    it does not apply to local variables.
86  - the names consists of a short (small letter) prefix,
87    the first letter of each following word is capitalized
88    (The routines Werror/WerrorS/Warn/WarnS/Print/PrintS have an empty prefix)
89  - the prefix describes the area the name belongs to:
90    p: polynomial operations
91    n/np/nl/na/: number operations (general/Zp/Q/alg.ext.)
92    k: std engine
93    ...
94  - _ (underscore) is only used as a last part of the prefix:
95    (example: p_Add): the last argument is the base ring
96  - macros are in capital letters (except used as a procedure)
97
98 
99
100- Comments
101  - class-/function-/member variable-/... comments should be written in the
102    doxygen format (see Doxygen quick reference card)
103  - documentation should explain the purpose of each type/function/parameter/.,
104    as well as its return value or any preconditions/side effects if applicable
105  - comments in source files about implementation details need not be in
106    doxygen format
107  - do not comment on trivial matters. Implementation details should be
108    sufficiently commented for others to understand the inner workings of the
109    code.
110  - document difficult algorithms by a reference to an article/book/etc.
111
112- Checks / Debugging aids
113  - interpreter routines have to check their input
114  - use const wherever possible/suitable (especially in declarations of input
115    parameters to functions/methods provided as pointers or references or for
116    methods that do not change the state of an object, consider delaring
117    variables "mutable" whenever suitable)
118
119  - kernel routines have to document their requirements,
120    the checks have to be done in the interpreter.
121    Repeat the checks only within #ifndef NDEBUG/#endif
122    or via assert.
123  - input should be checked to conform with the documentation via assume
124    (if this is simple)
125  - more time consuming tests should be within
126    #ifdef PDEBUG/#ifdef KDEBUG/#ifdef LDEBUG
127    (see mod2.h)
128  - case statements (or equivalent if/else constructs)
129    should always have an default entry
130    (maybe an error message)
131
132- C++ features
133  - to avoid confusion: "struct" should be a C object,
134    if you really need C++ extensions, use "class".
135  - "and"/"or"/"not" are not recognized by all compilers, use &&, &, ||, |, !
Note: See TracBrowser for help on using the repository browser.