Commit 13352f4d authored by BRAMAS Berenger's avatar BRAMAS Berenger
Browse files

Remove guide style to create a new one

parent 12917bdb
<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.0 Transitional//EN">
<HTML>
<HEAD>
<META HTTP-EQUIV="CONTENT-TYPE" CONTENT="text/html; charset=utf-8">
<TITLE></TITLE>
<META NAME="GENERATOR" CONTENT="LibreOffice 3.5 (Linux)">
<META NAME="AUTHOR" CONTENT="Berenger ">
<META NAME="CREATED" CONTENT="20110110;16562700">
<META NAME="CHANGEDBY" CONTENT="Berenger ">
<META NAME="CHANGED" CONTENT="20110324;10474900">
<STYLE TYPE="text/css">
<!--
@page { margin: 2cm }
P { margin-bottom: 0.21cm }
P.western { font-family: "Angleterre Book" }
P.cjk { font-size: 10pt }
H3 { margin-bottom: 0.21cm }
H3.western { font-family: "Liberation Serif", serif }
H3.ctl { font-family: "Lohit Hindi" }
TD P { margin-bottom: 0cm }
TD P.western { font-family: "Angleterre Book" }
TD P.cjk { font-size: 10pt }
H2 { margin-bottom: 0.21cm }
H2.western { font-family: "Liberation Serif", serif }
H2.ctl { font-family: "Lohit Hindi" }
H1 { margin-bottom: 0.21cm }
H1.western { font-family: "Liberation Sans", sans-serif; font-size: 16pt }
H1.cjk { font-family: "DejaVu Sans"; font-size: 16pt }
H1.ctl { font-family: "Lohit Hindi"; font-size: 16pt }
CODE.cjk { font-family: "DejaVu Sans", monospace }
-->
</STYLE>
</HEAD>
<BODY LANG="en-US" DIR="LTR">
<P ALIGN=CENTER STYLE="margin-top: 0.42cm; border-top: none; border-bottom: 2.50pt solid #000000; border-left: none; border-right: none; padding: 0cm; page-break-after: avoid">
<FONT FACE="Angleterre Book"><FONT SIZE=5><B>Style Guide - ScalFMM</B></FONT></FONT></P>
<H1 CLASS="western" STYLE="border-top: none; border-bottom: 1px solid #000000; border-left: none; border-right: none; padding: 0cm">
</H1>
<P CLASS="western" STYLE="border-top: none; border-bottom: 1px solid #000000; border-left: none; border-right: none; padding: 0cm">
This document present a style guideline and best practice for
ScalFMM.</P>
<P CLASS="western" STYLE="border-top: none; border-bottom: 1px solid #000000; border-left: none; border-right: none; padding: 0cm">
<BR><BR>
</P>
<H1 CLASS="western" STYLE="border-top: none; border-bottom: 1px solid #000000; border-left: none; border-right: none; padding: 0cm">
Comments</H1>
<P CLASS="western">In this part we describe the way to comment code.</P>
<H3 CLASS="western">Classes</H3>
<P CLASS="western">- optional : @class {class name} or
@interface<BR>@author {author(s)}<BR>@version {version}<BR>@date
{date}<BR>- optional : @file {file name}<BR>- optional : @package
{package name}<BR>(@brief) {short description}</P>
<P CLASS="western">- optional : @example</P>
<H3 CLASS="western">Example :</H3>
<DIV ID="highlighter_76344" DIR="LTR">
<TABLE WIDTH=479 CELLPADDING=0 CELLSPACING=0>
<COL WIDTH=17>
<COL WIDTH=461>
<TR>
<TD WIDTH=17 STYLE="border: none; padding: 0cm">
<P CLASS="western">1</P>
<P CLASS="western">2</P>
<P CLASS="western">3</P>
<P CLASS="western">4</P>
<P CLASS="western">5</P>
<P CLASS="western">6</P>
<P CLASS="western">7</P>
<P CLASS="western">8</P>
<P CLASS="western">9</P>
<P CLASS="western">10</P>
<P CLASS="western">11</P>
</TD>
<TD WIDTH=461 STYLE="border: none; padding: 0cm">
<P CLASS="western"><CODE CLASS="western">/**</CODE></P>
<P CLASS="western"><CODE CLASS="western">&nbsp;</CODE><CODE CLASS="western">*
@file </CODE><CODE CLASS="western">DBString</CODE><CODE CLASS="western">.c</CODE><CODE CLASS="western">pp</CODE></P>
<P CLASS="western"><CODE CLASS="western">&nbsp;</CODE><CODE CLASS="western">*
@brief My tests.</CODE></P>
<P CLASS="western"><CODE CLASS="western">&nbsp;</CODE><CODE CLASS="western">*&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;
more brief description</CODE></P>
<P CLASS="western"><CODE CLASS="western">&nbsp;</CODE><CODE CLASS="western">*
@author Franck.H</CODE></P>
<P CLASS="western"><CODE CLASS="western">&nbsp;</CODE><CODE CLASS="western">*
@version 0.1</CODE></P>
<P CLASS="western"><CODE CLASS="western">&nbsp;</CODE><CODE CLASS="western">*
@date September 6 2007</CODE></P>
<P CLASS="western"><CODE CLASS="western">&nbsp;</CODE><CODE CLASS="western">*</CODE></P>
<P CLASS="western"><CODE CLASS="western">&nbsp;</CODE><CODE CLASS="western">*
This class uses a string to connect to a DB.</CODE></P>
<P CLASS="western"><CODE CLASS="western">&nbsp;</CODE><CODE CLASS="western">*</CODE></P>
<P CLASS="western"><CODE CLASS="western">&nbsp;</CODE><CODE CLASS="western">*/</CODE></P>
</TD>
</TR>
</TABLE>
</DIV>
<H3 CLASS="western">Methods</H3>
<P CLASS="western">-optional : @fn {prototype}<BR>(@brief) {short
description}<BR>@author {author}<BR>@param &lt;name&gt; { description
}<BR>@return { description of the returned value }</P>
<UL>
<LI><P CLASS="western">optional : @example …</P>
<LI><P CLASS="western">optional : @warning ...</P>
<LI><P CLASS="western">optional : @complexity ...</P>
</UL>
<P CLASS="western">Describe the function objective and what it does
to succeed : what does it modify?</P>
<UL>
<LI><P CLASS="western">optional : give the algorithm</P>
</UL>
<P CLASS="western">Example :</P>
<DIV ID="highlighter_465422" DIR="LTR">
<TABLE WIDTH=566 CELLPADDING=0 CELLSPACING=0>
<COL WIDTH=17>
<COL WIDTH=549>
<TR>
<TD WIDTH=17 STYLE="border: none; padding: 0cm">
<P CLASS="western">1</P>
<P CLASS="western">2</P>
<P CLASS="western">3</P>
<P CLASS="western">4</P>
<P CLASS="western">5</P>
<P CLASS="western">6</P>
<P CLASS="western">7</P>
<P CLASS="western">8</P>
<P CLASS="western">9</P>
<P CLASS="western">10</P>
<P CLASS="western">11</P>
<P CLASS="western">12</P>
</TD>
<TD WIDTH=549 STYLE="border: none; padding: 0cm">
<P CLASS="western"><CODE CLASS="western">/**</CODE></P>
<P CLASS="western"><CODE CLASS="western">&nbsp;</CODE><CODE CLASS="western">*
@fn static Str_t * str_new (const char * sz)</CODE></P>
<P CLASS="western"><CODE CLASS="western">&nbsp;</CODE><CODE CLASS="western">*
@brief Create a new Str_t object.</CODE></P>
<P CLASS="western"><CODE CLASS="western">&nbsp;</CODE><CODE CLASS="western">*&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;
and increment a value</CODE></P>
<P CLASS="western"><CODE CLASS="western">&nbsp;</CODE><CODE CLASS="western">*</CODE></P>
<P CLASS="western"><CODE CLASS="western">&nbsp;</CODE><CODE CLASS="western">*
@param sz Array where to store Str_t, cannot be NULL.</CODE></P>
<P CLASS="western"><CODE CLASS="western">&nbsp;</CODE><CODE CLASS="western">*
@return New array Str_t or NULL in case of error</CODE></P>
<P CLASS="western"><CODE CLASS="western">&nbsp;</CODE><CODE CLASS="western">*</CODE></P>
<P CLASS="western"><CODE CLASS="western">&nbsp;</CODE><CODE CLASS="western">*
This function can be used like this or that</CODE></P>
<P CLASS="western"><CODE CLASS="western">&nbsp;</CODE><CODE CLASS="western">*
etc</CODE></P>
<P CLASS="western"><CODE CLASS="western">&nbsp;</CODE><CODE CLASS="western">*</CODE></P>
<P CLASS="western"><CODE CLASS="western">&nbsp;</CODE><CODE CLASS="western">*/</CODE></P>
</TD>
</TR>
</TABLE>
</DIV>
<H3 CLASS="western">Attributes</H3>
<P CLASS="western">Use “//&lt;” on the right of the attribute.</P>
<P CLASS="western">Example :</P>
<DIV ID="highlighter_605510" DIR="LTR">
<TABLE WIDTH=307 CELLPADDING=0 CELLSPACING=0>
<COL WIDTH=9>
<COL WIDTH=298>
<TR>
<TD WIDTH=9 STYLE="border: none; padding: 0cm">
<P CLASS="western">1</P>
</TD>
<TD WIDTH=298 STYLE="border: none; padding: 0cm">
<P CLASS="western"><CODE CLASS="western">int</CODE> <CODE CLASS="western">EVal1;
//&lt; enum value 1</CODE></P>
</TD>
</TR>
</TABLE>
</DIV>
<H3 CLASS="western">List</H3>
<P CLASS="western">If you need to write a list in your comment use :</P>
<DIV ID="highlighter_816860" DIR="LTR">
<TABLE WIDTH=353 CELLPADDING=0 CELLSPACING=0>
<COL WIDTH=9>
<COL WIDTH=343>
<TR>
<TD WIDTH=9 STYLE="border: none; padding: 0cm">
<P CLASS="western">1</P>
<P CLASS="western">2</P>
<P CLASS="western">3</P>
<P CLASS="western">4</P>
<P CLASS="western">5</P>
<P CLASS="western">6</P>
<P CLASS="western">7</P>
</TD>
<TD WIDTH=343 STYLE="border: none; padding: 0cm">
<P CLASS="western"><CODE CLASS="western">/**</CODE></P>
<P CLASS="western"><CODE CLASS="western">* @li at the beginning
of the lines</CODE></P>
<P CLASS="western"><CODE CLASS="western">* or html tags :</CODE></P>
<P CLASS="western"><CODE CLASS="western">* &lt;ol&gt;</CODE></P>
<P CLASS="western"><CODE CLASS="western">*&nbsp; &lt;li&gt;</CODE></P>
<P CLASS="western"><CODE CLASS="western">* &lt;/ol&gt;</CODE></P>
<P CLASS="western"><CODE CLASS="western">*/</CODE></P>
</TD>
</TR>
</TABLE>
</DIV>
<H3 CLASS="western">Mathematics</H3>
<P CLASS="western">You can write an equation like :</P>
<DIV ID="highlighter_275539" DIR="LTR">
<TABLE WIDTH=643 CELLPADDING=0 CELLSPACING=0>
<COL WIDTH=17>
<COL WIDTH=625>
<TR>
<TD WIDTH=17 STYLE="border: none; padding: 0cm">
<P CLASS="western">1</P>
<P CLASS="western">2</P>
<P CLASS="western">3</P>
<P CLASS="western">4</P>
<P CLASS="western">5</P>
<P CLASS="western">6</P>
<P CLASS="western">7</P>
<P CLASS="western">8</P>
<P CLASS="western">9</P>
<P CLASS="western">10</P>
<P CLASS="western">11</P>
</TD>
<TD WIDTH=625 STYLE="border: none; padding: 0cm">
<P CLASS="western"><CODE CLASS="western">/**</CODE></P>
<P CLASS="western"><CODE CLASS="western">* \f$
\sqrt{(x-x_0)^2-(y-y_0)^2} \f$ (it will generate a pretty draw)</CODE></P>
<P CLASS="western"><CODE CLASS="western">* x^{2}</CODE></P>
<P CLASS="western"><CODE CLASS="western">* \frac{x}{y}</CODE></P>
<P CLASS="western"><CODE CLASS="western">* \sum_{k=1}^n</CODE></P>
<P CLASS="western"><CODE CLASS="western">* \pi</CODE></P>
<P CLASS="western"><CODE CLASS="western">* x_{0}</CODE></P>
<P CLASS="western"><CODE CLASS="western">* \sqrt[n]{x}</CODE></P>
<P CLASS="western"><CODE CLASS="western">* \int_{a}^b dt</CODE></P>
<P CLASS="western"><CODE CLASS="western">* \Pi</CODE></P>
<P CLASS="western"><CODE CLASS="western">*/</CODE></P>
</TD>
</TR>
</TABLE>
</DIV>
<H3 CLASS="western">Use // like comments inside algorithm</H3>
<P CLASS="western">Try to avoid /* */ comments inside functions.</P>
<H3 CLASS="western">Complexity</H3>
<P CLASS="western">If needed, use :</P>
<DIV ID="highlighter_30387" DIR="LTR">
<TABLE WIDTH=186 CELLPADDING=0 CELLSPACING=0>
<COL WIDTH=9>
<COL WIDTH=177>
<TR>
<TD WIDTH=9 STYLE="border: none; padding: 0cm">
<P CLASS="western">1</P>
<P CLASS="western">2</P>
<P CLASS="western">3</P>
</TD>
<TD WIDTH=177 STYLE="border: none; padding: 0cm">
<P CLASS="western"><CODE CLASS="western">/**</CODE></P>
<P CLASS="western"><CODE CLASS="western">* @complexity O(n)</CODE></P>
<P CLASS="western"><CODE CLASS="western">*/</CODE></P>
</TD>
</TR>
</TABLE>
</DIV>
<H1 CLASS="western">Syntax – The minimum</H1>
<H3 CLASS="western">Static</H3>
<P CLASS="western">Every static things start with an Upper Char
:<BR>void StaticMethod();<BR>int StaticAttribute;</P>
<H3 CLASS="western">Classes</H3>
<P CLASS="western">If possible one class per file (with the same
name).<BR>The class name must starts with a upper letter.<BR>Please
give it the following constructor :</P>
<UL>
<LI><P CLASS="western" STYLE="margin-bottom: 0cm">default
constructor (no parameters)
</P>
<LI><P CLASS="western" STYLE="margin-bottom: 0cm">copy constructor
</P>
<LI><P CLASS="western" STYLE="margin-bottom: 0cm">copy operator
</P>
<LI><P CLASS="western" STYLE="margin-bottom: 0cm">destructor
(virtual)</P>
<LI><P CLASS="western">and all the constructors you need</P>
</UL>
<P CLASS="western">All methods (especially for getter/setter) with
less than 5 lines must be in the hpp (to be in-lined).</P>
<P CLASS="western">If needed use explicit for constructor safety.</P>
<H3 CLASS="western">Protection</H3>
<P CLASS="western">Use protected or private depending if you would
like to be inherited.</P>
<H3 CLASS="western">Variables</H3>
<P CLASS="western">Local variable [localVariable] : words in lower
letters with a upper letter at the beginning of words<BR>parameter
[inParameterFunction] : in at the beginning<BR>attribute
[this-&gt;attribute] : use this in big size function</P>
<P CLASS="western">index (indexArray or iteratorList) : put
information in the name (like indexCities etc.) not just i or j!</P>
<H2 CLASS="western">Tips &amp; Optimization</H2>
<H3 CLASS="western">Loops</H3>
<P CLASS="western">Use pre-inc (++index) and not post-inc (index++).</P>
<P CLASS="western">Do not create temporaries objects, for example
with iterator if you do like :</P>
<TABLE WIDTH=100% CELLPADDING=4 CELLSPACING=0>
<COL WIDTH=256*>
<TR>
<TD WIDTH=100% VALIGN=TOP STYLE="border: 1px solid #000000; padding: 0.1cm">
<P CLASS="western">for(Iter index = list.begin() ; index !=
list.end() ; ++index)</P>
</TD>
</TR>
</TABLE>
<P CLASS="western"><BR>you will create temporary object each loop
(with list.end() that returns an iterator).<BR>So do like :</P>
<TABLE WIDTH=100% CELLPADDING=4 CELLSPACING=0>
<COL WIDTH=256*>
<TR>
<TD WIDTH=100% VALIGN=TOP STYLE="border: 1px solid #000000; padding: 0.1cm">
<P CLASS="western">Iter end = list.end();<BR>for(Iter index =
list.begin() ; index != end ; ++index)</P>
</TD>
</TR>
</TABLE>
<P CLASS="western"><BR>We can put “return” directly in the loop,
it is faster than “break”.</P>
<H3 CLASS="western">Parameters</H3>
<P CLASS="western">Use references for objects and value for basic
types (int, float, etc).<BR>Use const every where you can.<BR>If you
need to modify an object use pointer not reference.</P>
<H3 CLASS="western">Const pointer</H3>
<P CLASS="western">Use Type* const var; if your pointer is not going
to target another object</P>
<H3 CLASS="western">Test</H3>
<P CLASS="western">We do not test with true/false/equal etc, so do
not write : if( variable == true )<BR>but : if( variable )</P>
<P CLASS="western">Do not test equality between decimal variables
(like double/float)<BR>You cannot do double1 == double2 with floating
value!<BR>You have to use something like Fmath::LookEqual</P>
<H3 CLASS="western">Declaring variables</H3>
<P CLASS="western">Declare variables by group of type (the int
together, the char together etc.)<BR>Declare variables when you have
something to put into.</P>
<H3 CLASS="western">Switch or if else</H3>
<P CLASS="western">With more than 3 if… if else … if else … if
you can use a switch or organize the tests.</P>
<H3 CLASS="western">Use iterative</H3>
<P CLASS="western">If possible use iterative and not recursive.</P>
<H3 CLASS="western">Comparing Array</H3>
<P CLASS="western">If you need to compare two array/string compare
the first value before creating a loop.</P>
<H3 CLASS="western">Cout</H3>
<P CLASS="western">std::endl put a ‘\n’ and flush the stream. So
use ‘\n’ and sometime use std::endl</P>
<H3 CLASS="western">Modulus</H3>
<P CLASS="western">For int value you can do : myInt % modInt =&gt;&gt;
myInt &amp; (modInt-1)</P>
<P CLASS="western">With integer value if you need to do %2, please
test the last bit<BR>myInt % 2 =&gt;&gt; myInt &amp; 0×01</P>
<P CLASS="western">But be carreful little indian big indian can make
problem.</P>
<P CLASS="western"><BR><BR>
</P>
<P CLASS="western">It is preferable to work in a way to avoid modulus
(by working smartly) :</P>
<P CLASS="western">++myVar; // only ++</P>
<P CLASS="western">myVar = myVar % 50; NO!</P>
<P CLASS="western">if( myVar &gt;= 50 ) myVar = 0;</P>
<H3 CLASS="western">Clone</H3>
<P CLASS="western">When you duplicate an object copy values with
memcpy and copy array/object etc…</P>
<P CLASS="western">Oject *o = new Object();<BR>memcpy(o, inObject ,
sizeof(Object));<BR>o.anObject = inObject;</P>
<H3 CLASS="western">Not null but 0</H3>
<P CLASS="western">Use 0 (not specially 0×00) to replace C Null<BR><BR><BR>
</P>
<H3 CLASS="western">Use C++ more than C Macro</H3>
<P CLASS="western">const TYPE<BR>enum<BR>are better than define</P>
<H3 CLASS="western">typedef</H3>
<P CLASS="western">Use typedef for changing type</P>
<H3 CLASS="western">int &amp; double</H3>
<P CLASS="western">Use int and double more than short/long/float etc.</P>
<H3 CLASS="western">Be careful when convert signed &amp; unsigned</H3>
<P CLASS="western">Do not use implicit cast between signed and
unsigned value</P>
<H3 CLASS="western">Use C++ cast more than C old-style cast</H3>
<P CLASS="western">static_cast : example int to short , or pointer to
another pointer etc.<BR>reinterpret : example int to
pointer<BR>dynamic_cast : for runtime cast<BR>const_cast : for
un-const/const only</P>
<P CLASS="western" STYLE="margin-bottom: 0cm"><BR>
</P>
<P CLASS="western" STYLE="margin-bottom: 0cm"><BR>
</P>
<P CLASS="western" STYLE="margin-bottom: 0cm"><BR><BR>
</P>
</BODY>
</HTML>
\ No newline at end of file
Markdown is supported
0% or .
You are about to add 0 people to the discussion. Proceed with caution.
Finish editing this message first!
Please register or to comment