Dec 22, 2008, 8:23:20 PM (15 years ago)

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

1 edited


  • trunk/README.developer

    r1673 r1674  
    3 = Requirements =
     3= Coding Style =
     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.
     11=== Testing ===
     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].
     15=== Interfacing [http://www.gnu.org/software/gsl/ Gnu Scientific Library, GSL] ===
     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.
     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:
     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.
     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:
     47   \brief My class
     49   Some text documenting the class MyClass
     51class MyClass
     54or similarly
     58   \brief magic function
     60   Some text documenting my_function
     62void my_function(void);
     65We use doxygen keywords preceded by `\` such as `\brief`, `\return`. All classes and functions have a brief description, which increases clarity on summary pages.
     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.
     69'''Internal Interface'''
     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`.
     74= Build =
     76== Requirements ==
    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.
    9 = Disable shared library =
     80 * Automake 1.10 (or later)
     81 * Autoconf 2.60 (or later)
     82 * Libtool.
     84== Disable shared library ==
    1186yat uses gnu Libtool in order to build shared libraries on a variety
    1590`--disable-shared` option to configure.
    17 = Debugging using GDB =
     92== Debugging using GDB ==
    1994If shared library is enabled (default), libtool creates wrapper
    32 = Enable svn-support =
     107== Enable svn-support ==
    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.
     115= Versioning =
     117We use a softened version of [http://apr.apache.org/versioning.html APR guidelines] which
     118in short implies
     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."''
     124== '''`MAJOR`''' Releases ==
     126No compatibility is guaranteed between '''`MAJOR`''' versions.
     128== '''`MINOR`''' Releases ==
     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.
     134== '''`PATCH`''' Releases ==
     136Versions with same '''`MAJOR.MINOR`''' are perfectly compatible,
     137forwards and backwards.
     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
     144=== Backward Source Compatibility ===
     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.
     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.
     159=== Backward Binary Compatibility ===
     161Backward Binary Compatibility means that an application that has been
     162compiled against version `x.y` can be linked against version
     165Specifically this implies:
     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.
     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
     177  - Do not add or change order among virtual functions because it will
     178    change the layout of the virtual table.
Note: See TracChangeset for help on using the changeset viewer.