Changeset 1674 for trunk/README.developer

Timestamp:

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

Author:

Peter

Message:

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

File:

• trunk/README.developer (modified) (4 diffs)

trunk/README.developer

@@ -1 +1 @@
 $Id$
 
-= Requirements =
+= Coding Style =
+
+We follow the coding style described in
+[http://cbbp.thep.lu.se/~jari/documents/c++_coding_guidelines/index.html C++ coding guidelines]
+[http://cbbp.thep.lu.se/~jari/documents/c++_coding_guidelines/c++_coding_guidelines.pdf pdf] 
+[http://cbbp.thep.lu.se/~jari/documents/c++_coding_guidelines/c++_coding_guidelines.ps postscript]
+with the additions described here.
+
+=== Testing ===
+
+The 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].
+
+=== Interfacing [http://www.gnu.org/software/gsl/ Gnu Scientific Library, GSL] ===
+
+The GSL documentation describes how
+[http://www.gnu.org/software/gsl/manual/html_node/Error-Handling.html#Error-Handling GSL error handling]
+works. The GSL library follows the thread-safe
+error reporting conventions of the posix Threads library. That is,
+functions return a non-zero error code to indicate an error. In most
+cases yat just returns whatever the underlying GSL library calls
+returns. If GSL errors occur in constructors yat handles them
+accordingly. If GSL reports errors that cannot be resolved by yat a
+[http://cbbp.thep.lu.se/~jari/documents/yat/classtheplu_1_1yat_1_1utility_1_1GSL__error.html GSL_error]
+exception will be thrown. However, the default behaviour of
+GSL library is to call abort() when unrecoverable errors occur and
+puts the yat (and any other) GSL error treatment out of play. For
+production environments, yat and GSL users should turn of the default
+GSL error treatment by calling gsl_set_error_handler_off(), but also
+when yat's GSL error treatment is preferred.
+
+When new GSL functionality is introduced to yat, it is the
+reponsibility of the programmer to make sure that GSL errors are
+treated properly. Proper GSL error treatment is very important in
+cases when yat users turn off the default GSL error handler since:
+
+yat aims at treating GSL errors appropriately in an
+[http://www.gotw.ca/gotw/008.htm exception safe and neutral]
+way but there is still some work to do before we do exceptions in a neutral way.
+
+=== Doxygen ===
+We 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:
+
+{{{
+/**
+   \brief My class
+
+   Some text documenting the class MyClass
+*/
+class MyClass
+}}}
+
+or similarly 
+
+{{{
+/**
+   \brief magic function
+
+   Some text documenting my_function
+*/
+void my_function(void);
+}}}
+
+We use doxygen keywords preceded by `\` such as `\brief`, `\return`. All classes and functions have a brief description, which increases clarity on summary pages. 
+
+Try 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. 
+
+'''Internal Interface'''
+
+Helper functions and classes that are not part of yat API should either be
+labeled with doxygen flag `\internal` or placed in sub-namespace `detail`. 
+
+= Build =
+
+== Requirements ==
 
 To build from a subversion checkout, you will need Autotools. More
-specifically Automake 1.10 (or later), Autoconf 2.60 (or later), and
-Libtool are required.
-
-= Disable shared library =
+specifically 
+ * Automake 1.10 (or later)
+ * Autoconf 2.60 (or later)
+ * Libtool.
+
+== Disable shared library ==
 
 yat uses gnu Libtool in order to build shared libraries on a variety
@@ -15 +90 @@
 `--disable-shared` option to configure.
 
-= Debugging using GDB =
+== Debugging using GDB ==
 
 If shared library is enabled (default), libtool creates wrapper
@@ -30 +105 @@
 http://www.gnu.org/software/libtool/manual/libtool.html#Debugging-executables
 
-= Enable svn-support =
+== Enable svn-support ==
 
 If you are building from an svn wc, you may run '`configure`' with
@@ -36 +111 @@
 targets. Most of the targets are useful at release time, i.e.,
 probably not very useful for other developers than the release
-manager. See '`build_support/svn_support.am`' for more details.
+manager. See [source:trunk/build_support/svn_support.am build_support/svn_support.am] for more details.
+
+= Versioning =
+
+We use a softened version of [http://apr.apache.org/versioning.html APR guidelines] which
+in short implies
+
+''"The basic intent is that '''`MAJOR`''' versions are incompatible,
+large-scale upgrades of the API. '''`MINOR`''' versions retain compatibility with older minor versions, and changes in the
+'''`PATCH`''' level are perfectly compatible, forwards and backwards."''
+
+== '''`MAJOR`''' Releases == 
+
+No compatibility is guaranteed between '''`MAJOR`''' versions.
+
+== '''`MINOR`''' Releases ==
+
+'''`MINOR`''' versions should be compatible with earlier minor
+versions. However, in the `0.x` line we may allow exceptions to this
+rule, 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. 
+ 
+== '''`PATCH`''' Releases ==
+
+Versions with same '''`MAJOR.MINOR`''' are perfectly compatible,
+forwards and backwards.
+ 
+This implies that only implementations can be modified in a `PATCH`
+release. You cannot change the API, not even add functions or
+classes because it will break forward compatibility for the previous
+`PATCH` version. A `PATCH` release is a pure bug fix release
+
+=== Backward Source Compatibility ===
+
+Backward Source Compatibility means that an application that could build
+against version `x.y` shall also build without error against
+`x.y+1`. An application that compiled against header files from
+previous `MINOR` version shall also compile without errors against the
+header files of the new version.
+
+Specifically this implies:
+  - Do not remove any public, protected, or free functions.
+  - If you modify a function, its signature must be compatible with
+    previous signature, e.g., new parameters with default values may
+    be aded to signature.
+  - Do not remove any class or inheritance for a class.
+
+=== Backward Binary Compatibility ===
+
+Backward Binary Compatibility means that an application that has been
+compiled against version `x.y` can be linked against version
+`x.y+1`. 
+
+Specifically this implies:
+
+  - Do not remove or modify any function (except private), not even
+    add a parameter with default value because it will make the
+    function incompatible with earlier header files.
+
+  - Do not add, remove, or modify member variables, because that will
+    change the allocated size of the class. Therefore, to allow
+    modifications of the internal representation, it is preferable to
+    hold member variable is a ''pimpl'' that is allocated privately.
+    http://developer.gnome.org/doc/guides/programming-guidelines/binary.html
+
+  - Do not add or change order among virtual functions because it will
+    change the layout of the virtual table.
+
+
+
 
 ----------------------------------------------------------------------