1# -*- org -*-
2
3* Names
4
5 - We are using the CamelCas naming convention. In C++, the first
6   letter is capitalized for class names, whereas it is not for method
7   names. Private attributes begin with an underscore followed by a
8   lower case letter.  Underscores are forbidden in class and method
9   names.
10
11 - SWIG is used to generate Python bindings. It processes headers
12   files to do its magic. Therefore the parameter names in headers are
13   not meaningless.
14
15* code style c, c++
16
17 - cf astyle documentation. We use ansi style with
18   unpad parenthesis and 2 spaces for indentation
19
20   astyle --style=ansi -U -v -s2
21
22* code style python
23
24  we prefer pep8 style
25  use [[../Tools/emacs/siconos-dot-emacs.el]]
26
27
28* Pointers
29 - We use a lot of shared_ptr (SP in Siconos) but make sure to not abuse them
30   since they come with a cost. For instant, in most case you should not pass
31   a SP as an argument. When a variable is used only locally or temporary, it
32   also usually not needed. The same applies to private attributes in classes
33   that are really private (not used outside the class).
34
35* Debug
36 - Do not use assert in constructor. Usually you need to do checks and throw
37   an exception if something is wrong. Furthermore in python it will either
38   kill the interpreter or fail silently.
39
40* Documentation
41We are using Doxygen to document the code. Please document a function or a
42method before its signature. Doxygen uses '/**' and '*/' as delimiter.
43- how to document function:
44
45/** function to compare bar and fun
46* \param bar an integer
47* \param fun an integer
48* \return 1 if fun > bar, 0 otherwise
49*/
50unsigned int foo(int bar, int fun);
51
52for the parameter, you can also also specify the direction using [in], [out]
53or [in, out]. Example:
54/** function to copy and multiply by a scalar
55* \param[in] x the input vector
56* \param[out] y the output vector
57* \param coeff the coefficient to apply
58*/
59void myaxpy(double * x, double * y, double coeff)
60
61- how to document variables:
62/** used to compute foo */
63unsigned int bar;
64
65- how to document a class:
66provide a brief description:
67/** \brief This class describe bar */
68
69and a detailed one
70/** This class is meant to ... blablabla ... */
71
72document all the attributes and the functions
73