xdocs/coding_conventions.html - axis-axis2-c-core - Git at Google

 <!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN">
 <html>
 <head>
   <meta http-equiv="Content-Type" content="">
   <title>Axis2/C Coding Conventions</title>
 </head>
 <body>
 <h1>Axis2/C Coding Conventions</h1>
 <p> </p>
 <h2>Contents</h2>
 <ul>
 <li><a href="#1_Naming_conventions_">Naming Conventions</a></li>
 <ul>
 <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>
 </ul>
 <li><a href="#2_Indentation">Indentation</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>
 </ul>
 <a name="1_Naming_conventions_"></a>
 <h2>1. Naming conventions </h2>
 <ul>
   <li>Namespace validation is done using the <strong>axis2_</strong>
 prefix. </li>
   <li>Underscore should be used to separate individual words in
 identifiers.</li>
   <li>All identifiers should be meaningful and abbreviations must be
 avoided whenever possible.</li>
 </ul>
 <a name="1.1_Variables"></a>
 <h3> 1.1 Variables</h3>
 <ul>
   <li>Use meaningful nouns.</li>
   <li>Make sure to use all lowercase letters for private &amp; public
 variables.</li>
   <li>If it is a local variable or a member of a struct, there's no
 need to prefix it with axis2_.</li>
 e.g.
   <pre>int count = 0;<br>char *prefix = NULL;<br></pre>
 </ul>
 <a name="1.2_Functions_"></a>
 <h3>1.2 Functions </h3>
 <ul>
   <li>Function names should always start with the prefix axis2_ except
 for members of a struct.</li>
 e.g.
   <pre><p>axis2_om_node_t * axis2_om_node_create(axis2_environment_t *environment);</p></pre>
 </ul>
 <a name="1.3_Structures_and_user_defined_data"></a>
 <h3>1.3 Structures
 and user defined data types </h3>
 <ul>
   <li>Note the _t suffix in the type name.</li>
 e.g.
   <pre>typedef struct axis2_om_namespace {<br>	char *uri;<br>	char *prefix;<br>} axis2_om_namespace_t;<br></pre>
 </ul>
 <a name="1.4_Macros"></a>
 <h3>1.4 Macros</h3>
 <ul>
   <li>Macro names should be in all uppercase letters, except when it is
 a macro
 to help hide the complexity of the use of function pointers in
 operation
 structs or when it is a type definition. </li>
 e.g.
   <pre>#define AXIS2_H<br><br>#define axis2_error_get_message(error) ((error)-&gt;ops-&gt;get_message())<br></pre>
 </ul>
 <a name="1.5_Enumerations"></a>
 <h3>1.5 Enumerations</h3>
 <ul>
 e.g.
   <pre>typedef enum axis2_status_codes {<br>	AXIS2_FAILURE = 0,<br>	AXIS2_SUCCESS<br>} axis2_status_codes_t;<br></pre>
 </ul>
 <a name="2_Indentation"></a>
 <h2>2. Indentation</h2>
 <ul>
 Indentation rules are defined in terms of GNU indent options:
 </ul>
 <ul>
 indent -nbad -bap -nbc -bbo -bl -bli0 -bls -ncdb -nce -cp1 -cs -di2
 -ndj
 -nfc1 -nfca -hnl -i4 -ip5 -lp -pcs -nprs -psl -saf -sai -saw -nsc -nsob
 -ts4
 -nut -nbfda
 </ul>
 <a name="3_Comments"></a>
 <h2>3. Comments</h2>
 <ul>
   <a href="http://www.stack.nl/%7Edimitri/doxygen/docblocks.html" target="_blank">Doxygen
 style comments</a> should be used to help auto generate API
 documentation.
 All structs as well as 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>
 <ul>
 Each function should be passed a pointer to an instance of
 axis2_environment_t 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>
 <ul>
 Functions returning pointers should return NULL in case of an error.
 The developer should make sure to set the relavant error code in
 environment's
 error struct.
 </ul>
 <ul>
 Functions returning none pointer values should always return
 AXIS2_FAILURE status code on error whenever possible, or some defined
 error value (in case of returning a struct may be). A relavant error code must also be set
 in environment's error struct.</ul>
 <a name="5_Include_directives"></a>
 <h2>5. Include directives</h2>
 <ul>
 It is prefereable to include header files in the following fashion:
 </ul>
 <ul>
   <pre>&lt;standard header files&gt;<br>&lt;other system headers&gt;<br>"local header files"<br></pre>
 </ul>
 </body>
 </html>
	<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN">
	<html>
	<head>
	<meta http-equiv="Content-Type" content="">
	<title>Axis2/C Coding Conventions</title>
	</head>
	<body>
	<h1>Axis2/C Coding Conventions</h1>
	<p> </p>
	<h2>Contents</h2>
	<ul>
	<li><a href="#1_Naming_conventions_">Naming Conventions</a></li>
	<ul>
	<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>
	</ul>
	<li><a href="#2_Indentation">Indentation</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>
	</ul>
	<a name="1_Naming_conventions_"></a>
	<h2>1. Naming conventions </h2>
	<ul>
	<li>Namespace validation is done using the <strong>axis2_</strong>
	prefix. </li>
	<li>Underscore should be used to separate individual words in
	identifiers.</li>
	<li>All identifiers should be meaningful and abbreviations must be
	avoided whenever possible.</li>
	</ul>
	<a name="1.1_Variables"></a>
	<h3> 1.1 Variables</h3>
	<ul>
	<li>Use meaningful nouns.</li>
	<li>Make sure to use all lowercase letters for private & public
	variables.</li>
	<li>If it is a local variable or a member of a struct, there's no
	need to prefix it with axis2_.</li>
	e.g.
	<pre>int count = 0;<br>char *prefix = NULL;<br></pre>
	</ul>
	<a name="1.2_Functions_"></a>
	<h3>1.2 Functions </h3>
	<ul>
	<li>Function names should always start with the prefix axis2_ except
	for members of a struct.</li>
	e.g.
	<pre><p>axis2_om_node_t * axis2_om_node_create(axis2_environment_t *environment);</p></pre>
	</ul>
	<a name="1.3_Structures_and_user_defined_data"></a>
	<h3>1.3 Structures
	and user defined data types </h3>
	<ul>
	<li>Note the _t suffix in the type name.</li>
	e.g.
	<pre>typedef struct axis2_om_namespace {<br> char uri;<br> char prefix;<br>} axis2_om_namespace_t;<br></pre>
	</ul>
	<a name="1.4_Macros"></a>
	<h3>1.4 Macros</h3>
	<ul>
	<li>Macro names should be in all uppercase letters, except when it is
	a macro
	to help hide the complexity of the use of function pointers in
	operation
	structs or when it is a type definition. </li>
	e.g.
	<pre>#define AXIS2_H<br><br>#define axis2_error_get_message(error) ((error)->ops->get_message())<br></pre>
	</ul>
	<a name="1.5_Enumerations"></a>
	<h3>1.5 Enumerations</h3>
	<ul>
	e.g.
	<pre>typedef enum axis2_status_codes {<br> AXIS2_FAILURE = 0,<br> AXIS2_SUCCESS<br>} axis2_status_codes_t;<br></pre>
	</ul>
	<a name="2_Indentation"></a>
	<h2>2. Indentation</h2>
	<ul>
	Indentation rules are defined in terms of GNU indent options:
	</ul>
	<ul>
	indent -nbad -bap -nbc -bbo -bl -bli0 -bls -ncdb -nce -cp1 -cs -di2
	-ndj
	-nfc1 -nfca -hnl -i4 -ip5 -lp -pcs -nprs -psl -saf -sai -saw -nsc -nsob
	-ts4
	-nut -nbfda
	</ul>
	<a name="3_Comments"></a>
	<h2>3. Comments</h2>
	<ul>
	<a href="http://www.stack.nl/%7Edimitri/doxygen/docblocks.html" target="_blank">Doxygen
	style comments</a> should be used to help auto generate API
	documentation.
	All structs as well as 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>
	<ul>
	Each function should be passed a pointer to an instance of
	axis2_environment_t 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>
	<ul>
	Functions returning pointers should return NULL in case of an error.
	The developer should make sure to set the relavant error code in
	environment's
	error struct.
	</ul>
	<ul>
	Functions returning none pointer values should always return
	AXIS2_FAILURE status code on error whenever possible, or some defined
	error value (in case of returning a struct may be). A relavant error code must also be set
	in environment's error struct.</ul>
	<a name="5_Include_directives"></a>
	<h2>5. Include directives</h2>
	<ul>
	It is prefereable to include header files in the following fashion:
	</ul>
	<ul>
	<pre><standard header files><br><other system headers><br>"local header files"<br></pre>
	</ul>
	</body>
	</html>