Changeset 51d7f7b in git for doc


Ignore:
Timestamp:
Jun 5, 2009, 4:34:06 AM (15 years ago)
Author:
Motsak Oleksandr <motsak@…>
Branches:
(u'fieker-DuVal', '117eb8c30fc9e991c4decca4832b1d19036c4c65')(u'spielwiese', 'b21a664aa22dc6e196223af8a74ad4885e83547c')
Children:
6dccbc5e8c728811407cb76468333f90ed59ee31
Parents:
01e88747d8875ada5e3d5eee6e8ef8a6a5509822
Message:
*motsak: some more


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

Legend:

Unmodified
Added
Removed
  • doc/C-STYLEGUIDE

    r01e8874 r51d7f7b  
    11C/C++-Style guide for Singular
    22-----------------------------
    3 - Header files
    4   - each header file abc.h should start with
    5     #ifndef ABC_H
    6     #define ABC_H
    7     and end with
    8     #endif
    9   - include only the header files you really need
    10   - do nor include mod2.h
    11 
    12 - C/C++ files - names
     3- C/C++ files - names (applies to headers as well)
    134  - each C++ file should have the extension .cc
    145  - each C file should have the extension .c
     
    2011
    2112- C/C++ files - structure
    22   - each C/C++ file (abc.c/abc.cc) should start with a short comment
    23     about its purpose
    24   - include first all system include files
    25   - include mod2.h
    26   - include all other files (which you really need)
     13  - TODO: What about Copyright note?
     14  - each C/C++ file (abc.c/abc.cc/abc.h) should start with a short comment
     15    about its purpose in doxygen format (TODO: see file templates) giving
     16    at least the filename and a brief description of the contents.
     17    TODO: should not contain CVS $Id: C-STYLEGUIDE,v 1.4 2009-06-05 02:34:06 motsak Exp $ tag!?
     18  - order "#include" statements from global to local scope:
     19      i. first: all system include files:
     20        #include <iostream>, #include <boost/shred_ptr.h>
     21     ii. only source files: #include "mod2.h"
     22    iii. at last: all other files (which you really need):
     23        #include "poly.h" etc.
     24  - paths in "#include" statements should be avoided (should be specified by
     25    build system level instead)
     26
     27- Header files
     28  - see C/C++ files - structure!
     29  - each header file abc.h should contain a multiple inclusions preventing
     30    mechanism as follows:
     31
     32    #ifndef ABC_H
     33    #define ABC_H
     34
     35    // .... declarations ...
     36
     37    #endif // ABC_H
     38
     39  - do NOT include mod2.h!
     40  - include only the header files you really need
     41    (use forward declarations wherever possible)
     42  - all declarations (macros, types, variables, enumerations, function
     43    parameters...) should be documented in doxygen format. Brief comments are
     44    mandatory, long comments are optional (TODO: see file templates)
     45  - class-/function-/member variable-/... comments should be written in the
     46    doxygen format (see Doxygen quick reference card)
     47  - further (non doxygen) comments can be used to separate the file into easily
     48    visible sections
    2749
    2850- format
    2951  - general screen width: 80 columns
    3052  - each procedure declarations should be in one line, if possible
     53  - the number of required function parameters should be as small as possible
    3154  - curly braces: Matching curly brackets should be either vertically
    32        or horizontally aligned.
    33   - the else keyword indents the same as its matching if
    34   - indentation should be small (e.g. two positions for each level of nesting)
     55    or horizontally aligned.
     56  - the "else" keyword indents the same as its matching "if"
     57  - indentation should be small
     58    (e.g. two positions (spaces) for each level of nesting)
    3559  - avoid tabs: their interpretation differs from editor to editor.
    3660  - use empty lines seldom: only to break up very long routines and between
    3761    routines
     62  - avoid code copying/duplication
     63  - declare local variables as late as possible and with the smallest possible
     64    visibility scope
     65  - avoid using "goto", "continue", "break" statements
     66    (save for "switch/case" blocks)
     67  - compiler warnings should be enabled and regarded as errors
     68  - whenever possible, constants should be defined as "const variables"
     69    not via "#define"
     70  - macroses should be avoided. Use "inline" functions instead
     71
    3872
    3973- Naming conventions:
     
    5387
    5488- Comments
    55   - each procedure should documents its input/output/side effects
    56     (-> automatic build of programmers manual)
    57   - do not comment on trivial matters
     89  - class-/function-/member variable-/... comments should be written in the
     90    doxygen format (see Doxygen quick reference card)
     91  - documentation should explain the purpose of each type/function/parameter/.,
     92    as well as its return value or any preconditions/side effects if applicable
     93  - comments in source files about implementation details need not be in
     94    doxygen format
     95  - do not comment on trivial matters. Implementation details should be
     96    sufficiently commented for others to understand the inner workings of the
     97    code.
    5898  - document difficult algorithms by a reference to an article/book/etc.
    5999
    60100- Checks / Debugging aids
    61101  - interpreter routines have to check their input
    62   - use const wherever possible/suitable
     102  - use const wherever possible/suitable (especially in declarations of input
     103    parameters to functions/methods provided as pointers or references or for
     104    methods that do not change the state of an object, consider delaring
     105    variables "mutable" whenever suitable)
     106
    63107  - kernel routines have to document their requirements,
    64108    the checks have to be done in the interpreter.
     
    69113  - more time consuming tests should be within
    70114    #ifdef PDEBUG/#ifdef KDEBUG/#ifdef LDEBUG
    71    (see mod2.h)
     115    (see mod2.h)
    72116  - case statements (or equivalent if/else constructs)
    73117    should always have an default entry
     
    78122    if you really need C++ extensions, use "class".
    79123  - "and"/"or"/"not" are not recognized by all compilers, use &&, &, ||, |, !
     124  - TODO: What about namespaces!?
     125
Note: See TracChangeset for help on using the changeset viewer.