View source for Olena/CodingStyle010

<noinclude>{{OlenaMenu}}</noinclude>

{{DISPLAYTITLE:Olena 0.10 Coding Style}}


To keep the code homogeneous and "easy" to read, any patch for Olena 0.10
should respect some rules. Several of them come from the style
guidelines of the libstdc++:
http://www.sunsite.ualberta.ca/Documentation/Gnu/libstdc++-2.90.8/html/17_intro/C++STYLE
.

This page is only a draft, all justified comments will be highly appreciated.



== Template indentation ==

* Choice

<syntaxhighlight lang="cpp" line enclose="div">
template <class T>
struct foo
{
};

// use typename if T includes non class types such as "int"
template <typename T>
struct foo
{
};

and not 

template <class T> 
struct foo {
};

or 

template <class T> struct foo {
};
</syntaxhighlight>

* Justifications

From the libstdc++ library.

== Function declaration indentation ==

* Choice

Always let the function name on a single line : 

<syntaxhighlight lang="cpp" line enclose="div">
static int
foo()
{
}

and not 

static int foo()
{
}
</syntaxhighlight>

especially when the return type is rather long: 

<syntaxhighlight lang="cpp" line enclose="div">
template <class T>
my_good_traits<T>::return_type
foo()
{
}
</syntaxhighlight>

* Justifications

Having the function name on one line has several advantages. First,
with a simple grep "^functioname", it's easy to find the definition of
a function. Moreover, when returns types are long or obfuscated, which
is often the case in Olena, it keeps the function name and arguments
easy to read.

== Function calls and declarations parenthesis rules ==

* Choice

<syntaxhighlight lang="cpp" line enclose="div">
void
foo(a, b) /* no space before the parenthesis */
{
}

foo(a, b)

and not

foo (a, b)
foo (a,b)
foo( a, b )

</syntaxhighlight>

* Justifications

First, when "foo" and "(" sticks together, it looks like a function (like in
mathematics); second, we are used to read such parenthesis (like this
present one) but not like ( this other one ).

Having arguments being well separated looks good (so "a,b" is
rejected).

Preferring foo(a, b) over foo( a, b ) is shorter and so stresses that
it is an entity separated from its environment.

== Method calls ==

* Choice

<syntaxhighlight lang="cpp" line enclose="div">
obj.m(...)

and not

obj . m
obj. m
</syntaxhighlight>

* Justifications

Not an intrinsics one, that is, the same as for function calls.

== Type declaration ==

* Choice

All lowercase, eg: 

<syntaxhighlight lang="cpp" line enclose="div">
class point;

template <class E>
class image;
</syntaxhighlight>

* Justifications

99% of use cases are declarations such as "point p;"
and there is no ambiguity (a declaration follows "type var;").

'point' cannot be a ''good'' name for a variable.  A "good" name
for a variable is p, p1, cur_p, current_p or p_prime, that is, a name
that explains what is the particular point in the algorithm.
Having a point named 'point' does not hold enough information
(if there's no information to give about a particular point then
call p this point!)

'point' cannot conflict with another type name since we use
namespace.  'point' is in fact 'oln::point'.

This choice is the one of the C++ std lib.  All these justifications
go for std::list!

The simplest the best.

With modern editors there are different highlighting colors for types
and variables.

Writings such as type_something are longer and does not lead to more
explicit code.  I claim that "point_t p;" is less easily readable
(parsable by human eyes) than "point p;".  This question is equivalent
to the one of "type* var_ptr / type& var_ref / type var" (a fashion
that is now obsolete because code was more complex to read than
explicit).  The compiler avoids the programmer to confuse var->x and
var.x that the same for types v. variables!

== Declarations with modifed types (*, &) ==

* Choice

<syntaxhighlight lang="cpp" line enclose="div">
type* var;
type& var;
</syntaxhighlight>

* Justifications

On the left (before the space delim) the precise type, on the right
the variable name.  This justification is the one that makes this
convention being well-spread.

Variable names are easier to read (by human eyes) and we are going to
use them (not their type names).

== Macro on types returning types ==

* Choice

<syntaxhighlight lang="cpp" line enclose="div">
oln_point_type(I) p;
oln_value_type(I) val;
ntg_value_type(u_int8) v;
</syntaxhighlight>

* Justifications

** no namespaces for macros ==> how can the user determine the
origin of a macro ? In C, people used to prefix any functions with the
project name, "simulating" namespaces. We are in this case with macro
yet.  And there is a high risk of clashes with user of other libraries
macros. Indeed, if libraries such as Boost applied the same convention
(ie. without prefix), there would be many clashes I think. So this
approach does not seem quite reliable.

** We need to specify the kind of thing the macro returns, so we need a
suffix (_type of _val). Indeed, there are several cases where the
same macro name can refer to different kind of objects.

We cannot escape from these 2 constraints. Thus, the only choice left
concerns letter cases:

<syntaxhighlight lang="cpp" line enclose="div">
oln_Point_type(I)
Oln_Point_Type(I)
oln_point_type(I)
OLN_POINT_TYPE(I)
// many other variants possible
</syntaxhighlight>

The all caps version has the advantage to be commonly admitted to warn
the user that it is a macro. Indeed, historically there is a
difference between sqr(i) and SQR(i).  On one hand, the user knows
that it is a "real" function call so she knows that it's safe to write
sqr(++i).  On the other hand, it's a macro so she has to be careful
when using it.  This style convention has been settled to warn the
user when the square root function is defined by a macro.  I guess
that this is the ''only'' justification of upcases for macros.

This justification does not hold for ''our'' macros since they
apply on type(s)!

So we can choose the more readable version, which appeared to be all
lower case.

== Macros on types returning values ==

* Choice

<syntaxhighlight lang="cpp" line enclose="div">
int dim = oln_dim_val(I);
int max = ntg_max_val(u_int8);
</syntaxhighlight>

* Justifications

Coherent with macros on types returning types convention.

== Traits returning types ==

* Choice

** Dedicated traits (1)

<syntaxhighlight lang="cpp" line enclose="div">
value_type<T>::ret v;
point_type<T>::ret p;

// and NOT

value_type<T>::ret_t; // WRONG
value_type<T>::res; // WRONG
value_type<T>::return_type; // WRONG

value<T>::ret; // WRONG
</syntaxhighlight>

** Grouping traits (2)

<syntaxhighlight lang="cpp" line enclose="div">
traits<T>::value_type;
traits<T>::point_type;

// and NOT

traits<T>::value; // WRONG
traits<T>::value_t; // WRONG
</syntaxhighlight>

* Justifications

For (1), we know that the return value will be a type, so the shortest
syntax is the best one (value_type<T>::ret). ret is more commonly used
than res, so we prefer ret.

For (2), traits<T>::value_type gives informations about the type of
the returned thing. xxx_t looks too close from the std::*_t reserved
types.


== Traits returning values ==

* Choice

** Dedicated traits (1)

<syntaxhighlight lang="cpp" line enclose="div">
dim_val<T>::ret
</syntaxhighlight>

** Grouping traits (2)

<syntaxhighlight lang="cpp" line enclose="div">
traits<T>::dim_val
</syntaxhighlight>

* Justifications

To be coherent with traits returning types.

== Comments ==

* Choice

<syntaxhighlight lang="cpp" line enclose="div">
/*-------.
{| class="wikitable"
|-
| foobar 
|}

`-------*/

//! Brief description of Foobar
/*!
  This is the complete description of the foobar class, bla bla bla.
  The second line starts here.
  blablabla.
*/
struct foobar
{};
</syntaxhighlight>

* Justifications

These are comments in doxygen style, I find them quite clear and using
them will help us if we decide to use doxygen on the future. The box
containing the name of the class is really easy to create with a well
configured emacs, and facilitate the reading of long headers I think.