Ignore:
Timestamp:
Dec 22, 2008, 8:23:20 PM (12 years ago)
Author:
Peter
Message:

merging wiki:CodingStyle? into README.developer - refs #458

File:
1 edited

Legend:

Unmodified
Added
Removed
  • trunk/README.developer

    r1673 r1674  
    11$Id$
    22
    3 = Requirements =
     3= Coding Style =
     4
     5We follow the coding style described in
     6[http://cbbp.thep.lu.se/~jari/documents/c++_coding_guidelines/index.html C++ coding guidelines]
     7[http://cbbp.thep.lu.se/~jari/documents/c++_coding_guidelines/c++_coding_guidelines.pdf pdf]
     8[http://cbbp.thep.lu.se/~jari/documents/c++_coding_guidelines/c++_coding_guidelines.ps postscript]
     9with the additions described here.
     10
     11=== Testing ===
     12
     13The test suite should at minimum include creation of all classes (to catch linking errors) and calls to template functions (as template functions are not compiled until they are needed). For more details on writing test, see file [source:trunk/test/README test/README].
     14
     15=== Interfacing [http://www.gnu.org/software/gsl/ Gnu Scientific Library, GSL] ===
     16
     17The GSL documentation describes how
     18[http://www.gnu.org/software/gsl/manual/html_node/Error-Handling.html#Error-Handling GSL error handling]
     19works. The GSL library follows the thread-safe
     20error reporting conventions of the posix Threads library. That is,
     21functions return a non-zero error code to indicate an error. In most
     22cases yat just returns whatever the underlying GSL library calls
     23returns. If GSL errors occur in constructors yat handles them
     24accordingly. If GSL reports errors that cannot be resolved by yat a
     25[http://cbbp.thep.lu.se/~jari/documents/yat/classtheplu_1_1yat_1_1utility_1_1GSL__error.html GSL_error]
     26exception will be thrown. However, the default behaviour of
     27GSL library is to call abort() when unrecoverable errors occur and
     28puts the yat (and any other) GSL error treatment out of play. For
     29production environments, yat and GSL users should turn of the default
     30GSL error treatment by calling gsl_set_error_handler_off(), but also
     31when yat's GSL error treatment is preferred.
     32
     33When new GSL functionality is introduced to yat, it is the
     34reponsibility of the programmer to make sure that GSL errors are
     35treated properly. Proper GSL error treatment is very important in
     36cases when yat users turn off the default GSL error handler since:
     37
     38yat aims at treating GSL errors appropriately in an
     39[http://www.gotw.ca/gotw/008.htm exception safe and neutral]
     40way but there is still some work to do before we do exceptions in a neutral way.
     41
     42=== Doxygen ===
     43We generate our documentation using [http://www.doxygen.org Doxygen] (version 1.5 or later). Doxygen allows several different styles. We try to use the following style as we have found this minimizes parsing problems:
     44
     45{{{
     46/**
     47   \brief My class
     48
     49   Some text documenting the class MyClass
     50*/
     51class MyClass
     52}}}
     53
     54or similarly
     55
     56{{{
     57/**
     58   \brief magic function
     59
     60   Some text documenting my_function
     61*/
     62void my_function(void);
     63}}}
     64
     65We use doxygen keywords preceded by `\` such as `\brief`, `\return`. All classes and functions have a brief description, which increases clarity on summary pages.
     66
     67Try to keep comment line lengths within the terminal character limit, in other words, less than 80 characters per line. This makes the comments more readable.
     68
     69'''Internal Interface'''
     70
     71Helper functions and classes that are not part of yat API should either be
     72labeled with doxygen flag `\internal` or placed in sub-namespace `detail`.
     73
     74= Build =
     75
     76== Requirements ==
    477
    578To build from a subversion checkout, you will need Autotools. More
    6 specifically Automake 1.10 (or later), Autoconf 2.60 (or later), and
    7 Libtool are required.
    8 
    9 = Disable shared library =
     79specifically
     80 * Automake 1.10 (or later)
     81 * Autoconf 2.60 (or later)
     82 * Libtool.
     83
     84== Disable shared library ==
    1085
    1186yat uses gnu Libtool in order to build shared libraries on a variety
     
    1590`--disable-shared` option to configure.
    1691
    17 = Debugging using GDB =
     92== Debugging using GDB ==
    1893
    1994If shared library is enabled (default), libtool creates wrapper
     
    30105http://www.gnu.org/software/libtool/manual/libtool.html#Debugging-executables
    31106
    32 = Enable svn-support =
     107== Enable svn-support ==
    33108
    34109If you are building from an svn wc, you may run '`configure`' with
     
    36111targets. Most of the targets are useful at release time, i.e.,
    37112probably not very useful for other developers than the release
    38 manager. See '`build_support/svn_support.am`' for more details.
     113manager. See [source:trunk/build_support/svn_support.am build_support/svn_support.am] for more details.
     114
     115= Versioning =
     116
     117We use a softened version of [http://apr.apache.org/versioning.html APR guidelines] which
     118in short implies
     119
     120''"The basic intent is that '''`MAJOR`''' versions are incompatible,
     121large-scale upgrades of the API. '''`MINOR`''' versions retain compatibility with older minor versions, and changes in the
     122'''`PATCH`''' level are perfectly compatible, forwards and backwards."''
     123
     124== '''`MAJOR`''' Releases ==
     125
     126No compatibility is guaranteed between '''`MAJOR`''' versions.
     127
     128== '''`MINOR`''' Releases ==
     129
     130'''`MINOR`''' versions should be compatible with earlier minor
     131versions. However, in the `0.x` line we may allow exceptions to this
     132rule, if developers agree the gain of change is sufficient. Binary compatibility is typically not guaranteed between '''`MINOR`''' versions. The `YAT_LT_VERSION` in [source:trunk/build_support/version.m4 version.m4] should reflect which versions are binary compatible.
     133 
     134== '''`PATCH`''' Releases ==
     135
     136Versions with same '''`MAJOR.MINOR`''' are perfectly compatible,
     137forwards and backwards.
     138 
     139This implies that only implementations can be modified in a `PATCH`
     140release. You cannot change the API, not even add functions or
     141classes because it will break forward compatibility for the previous
     142`PATCH` version. A `PATCH` release is a pure bug fix release
     143
     144=== Backward Source Compatibility ===
     145
     146Backward Source Compatibility means that an application that could build
     147against version `x.y` shall also build without error against
     148`x.y+1`. An application that compiled against header files from
     149previous `MINOR` version shall also compile without errors against the
     150header files of the new version.
     151
     152Specifically this implies:
     153  - Do not remove any public, protected, or free functions.
     154  - If you modify a function, its signature must be compatible with
     155    previous signature, e.g., new parameters with default values may
     156    be aded to signature.
     157  - Do not remove any class or inheritance for a class.
     158
     159=== Backward Binary Compatibility ===
     160
     161Backward Binary Compatibility means that an application that has been
     162compiled against version `x.y` can be linked against version
     163`x.y+1`.
     164
     165Specifically this implies:
     166
     167  - Do not remove or modify any function (except private), not even
     168    add a parameter with default value because it will make the
     169    function incompatible with earlier header files.
     170
     171  - Do not add, remove, or modify member variables, because that will
     172    change the allocated size of the class. Therefore, to allow
     173    modifications of the internal representation, it is preferable to
     174    hold member variable is a ''pimpl'' that is allocated privately.
     175    http://developer.gnome.org/doc/guides/programming-guidelines/binary.html
     176
     177  - Do not add or change order among virtual functions because it will
     178    change the layout of the virtual table.
     179
     180
     181
    39182
    40183----------------------------------------------------------------------
Note: See TracChangeset for help on using the changeset viewer.