blob: 65978693808f42ad4e8be080c692bc6a7e62946c [file] [log] [blame]
<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN">
<meta http-equiv="content-type" content="">
<title>Coding Conventions</title>
<h1>Axis2/C Coding Conventions</h1>
<li><a href="#1_Naming_conventions_">Naming Conventions</a>
<li><a href="#1.1_Variables">Variables</a></li>
<li><a href="#1.2_Functions_">Functions</a></li>
<li><a href="#1.3_Structures_and_user_defined_data">Structures and User
defined Data Types</a></li>
<li><a href="#1.4_Macros">Macros</a></li>
<li><a href="#1.5_Enumerations">Enumerations</a></li>
<li><a href="#2_Indentation">Indentation and Formatting</a></li>
<li><a href="#3_Comments">Comments</a></li>
<li><a href="#4_Function_parameters_and_Return_Value">Function Parameters
and Return Value Conventions</a></li>
<li><a href="#5_Include_directives">Include Directives</a></li>
<a name="1_Naming_conventions_"></a>
<h2>1. Naming Conventions</h2>
<li>Namespace validation is done using the
<code><strong>axis2_</strong></code> prefix.</li>
<li>Underscore should be used to separate individual words in
<li>All identifiers should be meaningful and abbreviations must be avoided
whenever possible.</li>
<a name="1.1_Variables"></a>
<h3>1.1 Variables</h3>
<li>Use meaningful nouns.</li>
<li>Make sure to use all lowercase letters for private and public
<li>If it is a local variable or a member of a struct, there's no need to
prefix it with <code>axis2_</code></li>
<pre>int count = 0;
char *prefix = NULL;</pre>
<a name="1.2_Functions_"></a>
<h3>1.2 Functions</h3>
<li>Function names should always start with the prefix <code>axis2_</code>
except for members of a struct.</li>
<pre>axis2_engine_t * axis2_engine_create(axutil_env_t *environment);</pre>
<a name="1.3_Structures_and_user_defined_data"></a>
<h3>1.3 Structures and User Defined Data Types</h3>
<li>Note the _t suffix in the type name.</li>
<pre>typedef struct axis2_endpoint_ref {
axis2_char_t *address;
} axis2_endpoint_ref_t;</pre>
<a name="1.4_Macros"></a>
<h3>1.4 Macros</h3>
<li>Macro names should be in all uppercase letters.</li>
<pre>#define AXIS2_H
#define AXIS2_ERROR_GET_MESSAGE(error) ((error)-&gt;ops-&gt;get_message(error))
<a name="1.5_Enumerations"></a>
<h3>1.5 Enumerations</h3>
<pre>typedef enum axis2_status_codes {
} axis2_status_codes_t;</pre>
<a name="2_Indentation"></a>
<h2>2. Indentation and Formatting</h2>
Indentation rules are defined in terms of <a
href="">Artistic Style</a> indent
<!--indent -nbad -bap -nbc -bbo -bl -bli0 -bls -ncdb -nce -cp1 -cs -di2
-nfc1 -nfca -hnl -i4 -ip5 -lp -pcs -nprs -psl -saf -sai -saw -nsc -nsob
-nut -nbfda-->
astyle --style=ansi -b -p -s4 -M0 -c -U -S</ul>
In detail, these options mean,
<li>Use the ANSI style code layout
<pre> int foo()
if (is_bar)
return 1;
return 0;
<li>Use spaces around operators</li>
<li>Use four spaces for indenting</li>
<li>No spaces between the function name and parenthesis
<pre> if (is_foo(a, b))
bar(a, b);
<pre> </pre>
There are some more formatting guidelines that could not be enforced by a
formatting tool, but nevertheless should be followed.
<li>Checking pointer validity:
<pre> if (foo)</pre>
and NOT
<pre> if (foo != NULL)</pre>
<li>Checking equality:
<pre> if (foo == 7)</pre>
and NOT
<pre> if (7 == foo)</pre>
<a name="3_Comments"></a>
<h2>3. Comments</h2>
<a href=""
target="_blank">Doxygen style comments</a> should be used to help auto
generate API documentation. All structs and functions including parameters
and return types should be documented.</ul>
<a name="4_Function_parameters_and_Return_Value"></a>
<h2>4. Function Parameters and Return Value Conventions</h2>
Each function should be passed a pointer to an instance of the
<code>axutil_env_t</code> struct as the first parameter. If the
function is tightly bound to a struct, the second parameter is a pointer to
an instance of that struct.</ul>
Functions returning pointers should return NULL in case of an error. The
developer should make sure to set the relevant error code in the
environment's error struct.</ul>
Functions that do not return pointer values should always return the
<code>AXIS2_FAILURE</code> status code on error whenever possible, or
return some other defined error value (in case of returning a struct
perhaps). A relevant error code must also be set in the environment's error
<a name="5_Include_directives"></a>
<h2>5. Include Directives</h2>
It is preferable to include header files in the following fashion:</ul>
<pre>&lt;standard header files&gt;
&lt;other system headers&gt;
"local header files"</pre>