source: git/doc/C-STYLEGUIDE @ 4a1b604

Last change on this file since 4a1b604 was 4a1b604, checked in by Motsak Oleksandr <motsak@…>, 14 years ago
*motsak: cvs id tag git-svn-id: file:///usr/local/Singular/svn/trunk@11885 2c84dea3-7e68-4137-9b89-c4e89433aadc
  • Property mode set to 100644
File size: 5.9 KB
1C/C++-Style guide for Singular
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
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/ 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)
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:
34    #ifndef ABC_H
35    #define ABC_H
37    // .... declarations ...
39    #endif // ABC_H
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
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
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)
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)
98- Comments
99  - class-/function-/member variable-/... comments should be written in the
100    doxygen format (see Doxygen quick reference card)
101  - documentation should explain the purpose of each type/function/parameter/.,
102    as well as its return value or any preconditions/side effects if applicable
103  - comments in source files about implementation details need not be in
104    doxygen format
105  - do not comment on trivial matters. Implementation details should be
106    sufficiently commented for others to understand the inner workings of the
107    code.
108  - document difficult algorithms by a reference to an article/book/etc.
110- Checks / Debugging aids
111  - interpreter routines have to check their input
112  - use const wherever possible/suitable (especially in declarations of input
113    parameters to functions/methods provided as pointers or references or for
114    methods that do not change the state of an object, consider delaring
115    variables "mutable" whenever suitable)
117  - kernel routines have to document their requirements,
118    the checks have to be done in the interpreter.
119    Repeat the checks only within #ifndef NDEBUG/#endif
120    or via assert.
121  - input should be checked to conform with the documentation via assume
122    (if this is simple)
123  - more time consuming tests should be within
124    #ifdef PDEBUG/#ifdef KDEBUG/#ifdef LDEBUG
125    (see mod2.h)
126  - case statements (or equivalent if/else constructs)
127    should always have an default entry
128    (maybe an error message)
130- C++ features
131  - to avoid confusion: "struct" should be a C object,
132    if you really need C++ extensions, use "class".
133  - "and"/"or"/"not" are not recognized by all compilers, use &&, &, ||, |, !
134  - TODO: What about namespaces!?
Note: See TracBrowser for help on using the repository browser.