| <!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN"> |
| <html> |
| <head> |
| <title>Axis2/C Coding Conventions</title> |
| </head> |
| <body> |
| <h1>Axis2/C Coding Conventions</h1> |
| <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 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> |
| </ul> |
| <a name="1_Naming_conventions_"></a> |
| <h2>1. Naming conventions </h2> |
| <ul> |
| <li>Namespace validation is done using the <code><strong>axis2_</strong></code> |
| 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 <code>axis2_</code>.</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 <code>axis2_</code> 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. </li> |
| e.g. |
| <pre>#define AXIS2_H<br><br>#define AXIS2_ERROR_GET_MESSAGE(error) ((error)->ops->get_message(error))<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 and Formatting</h2> |
| <ul> |
| Indentation rules are defined in terms of <a href "http://astyle.sourceforge.net/">Artistic Style</a> 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--> |
| astyle --style=ansi -b -p -s4 -M0 -c -U -S |
| </ul> |
| <ul> |
| In detail, these options mean: |
| <ul> |
| <li> |
| Use ANSI style code layout |
| <pre> |
| int foo() |
| { |
| if (is_bar) |
| { |
| bar(); |
| return 1; |
| } |
| else |
| return 0; |
| } |
| </pre> |
| </li> |
| <li> |
| Use spaces around operators |
| </li> |
| <li> |
| Use four spaces for indenting |
| </li> |
| <li> |
| No spaces between function name and parenthesis |
| <pre> |
| if (is_foo(a, b)) |
| bar(a, b); |
| <pre> |
| </li> |
| </ul> |
| |
| There are some more formatting guidelines that could not be enforced by a |
| formatting tool, but nevertheless should be followed |
| <ul> |
| <li> |
| Checking pointer validity: |
| <pre> |
| if (foo) |
| </pre> |
| and NOT |
| <pre> |
| if (foo != NULL) |
| </pre> |
| </li> |
| <li> |
| Checking equality: |
| <pre> |
| if (foo == 7) |
| </pre> |
| and NOT |
| <pre> |
| if (7 == foo) |
| </pre> |
| </li> |
| |
| </ul> |
| |
| </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 <code>axis2_environment_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> |
| <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> |
| <ul> |
| Functions returning none pointer values should always return |
| <code>AXIS2_FAILURE</code> status code on error whenever possible, or some defined |
| error value (in case of returning a struct may be). A relevant 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 preferable 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> |
