Forgot your password?
C Style Guide
<ul><li> <a name="tex2html1" href="#SECTION00020000000000000000">Introduction</a> </li><li> <a name="tex2html2" href="#SECTION00030000000000000000">Layout</a> <ul><li> <a name="tex2html3" href="#SECTION00031000000000000000">General</a> </li><li> <a name="tex2html4" href="#SECTION00032000000000000000">Module</a> <ul><li> <a name="tex2html5" href="#SECTION00032100000000000000"><tt>.h</tt> File</a> </li><li> <a name="tex2html6" href="#SECTION00032200000000000000"><tt>.c</tt> File</a> </li><li> <a name="tex2html7" href="#SECTION00032300000000000000"><tt>.uil</tt> File</a> </li></ul> </li><li> <a name="tex2html8" href="#SECTION00033000000000000000"><tt>struct</tt> Declaration</a> <ul><li> <a name="tex2html9" href="#SECTION00033100000000000000">Top Level</a> </li><li> <a name="tex2html10" href="#SECTION00033200000000000000">As a Field</a> </li></ul> </li><li> <a name="tex2html11" href="#SECTION00034000000000000000"><tt>union</tt> Declaration</a> </li><li> <a name="tex2html12" href="#SECTION00035000000000000000"><tt>enum</tt> Declaration</a> </li><li> <a name="tex2html13" href="#SECTION00036000000000000000">Function Prototype</a> </li><li> <a name="tex2html14" href="#SECTION00037000000000000000">Function Definition</a> </li><li> <a name="tex2html15" href="#SECTION00038000000000000000">Variable Declarations</a> </li><li> <a name="tex2html16" href="#SECTION00039000000000000000"><tt>if</tt> Statement</a> </li><li> <a name="tex2html17" href="#SECTION000310000000000000000"><tt>do</tt> Statement</a> </li><li> <a name="tex2html18" href="#SECTION000311000000000000000"><tt>while</tt> Statement</a> </li><li> <a name="tex2html19" href="#SECTION000312000000000000000"><tt>for</tt> Statement</a> </li><li> <a name="tex2html20" href="#SECTION000313000000000000000"><tt>switch</tt> Statement</a> </li><li> <a name="tex2html21" href="#SECTION000314000000000000000">Debug Statements</a> </li><li> <a name="tex2html22" href="#SECTION000315000000000000000">Comments</a> </li></ul> </li><li> <a name="tex2html23" href="#SECTION00040000000000000000">Style</a> <ul><li> <a name="tex2html24" href="#SECTION00041000000000000000">return</a> </li><li> <a name="tex2html25" href="#SECTION00042000000000000000"><tt>exit</tt></a> </li><li> <a name="tex2html26" href="#SECTION00043000000000000000"><tt>break</tt></a> </li><li> <a name="tex2html27" href="#SECTION00044000000000000000"><tt>continue</tt></a> </li><li> <a name="tex2html28" href="#SECTION00045000000000000000"><tt>goto</tt></a> </li><li> <a name="tex2html29" href="#SECTION00046000000000000000"><tt>elseif</tt></a> </li><li> <a name="tex2html30" href="#SECTION00047000000000000000"><tt>typedef</tt></a> </li><li> <a name="tex2html31" href="#SECTION00048000000000000000">Memory Allocation</a> </li><li> <a name="tex2html32" href="#SECTION00049000000000000000"><tt>ENTER</tt> and <tt>LEAVE</tt> (in <tt>general/debug.h</tt>)</a> </li><li> <a name="tex2html33" href="#SECTION000410000000000000000">Comments</a> </li><li> <a name="tex2html34" href="#SECTION000411000000000000000">Clarity</a> </li><li> <a name="tex2html35" href="#SECTION000412000000000000000">Lists</a> </li><li> <a name="tex2html36" href="#SECTION000413000000000000000">Casting <tt>NULL</tt></a> </li></ul> </li></ul> <h1><a name="SECTION00020000000000000000">Introduction</a></h1> <p> The style and layout to be used for programming on cmgui, cmulgeom, gx, mulgraph, emap and related projects. </p><p> For the examples in this document, <tt><</tt> and <tt>></tt> are used to enclose things that depend on the instance. </p><p> For questions, clarification or justification see David Bullivant. </p><p> </p><h1><a name="SECTION00030000000000000000">Layout</a></h1> <p> </p><h2><a name="SECTION00031000000000000000">General</a></h2> <p> </p><ul><li> Tabs are used for indentation. </li><li> A tab is 2 spaces. </li><li> Tabs are only used for indentation (can only appear at the beginning of
a line).
</li><li> The line length is 80 characters (with tabs counting as 2 spaces). </li><li> If a statement extends over more than one line then the extension lines
are indented one tab from the first line (includes comments).
- </li><li> For a compound statement, the <tt>{</tt> and <tt>}</tt> are on
- separate lines and have the same level of indentation as the statment it is a condition of. The body of the compound statement should be indented by 1 tab, <em>e.g.,</em>
<pre>if (<condition>)<br>{<br> <body><br>}</pre> </li><li> There should be no trailing spaces or tabs. </li><li> <tt>#ifdef</tt> and <tt>#ifndef</tt> are not used. <tt>#if
defined (<MACRO>)</tt> and <tt>#if !defined (MACRO)</tt> are used instead.
- </li><li> No spaces after <tt>,</tt>'s or around operators, except
- <tt>*=</tt>, <tt>/=</tt>, <tt>+=</tt>, <tt>-=</tt>, <tt>%=</tt>, <tt><<=</tt>, <tt>>>=</tt>, <tt>&=</tt>, <tt>=</tt> and <tt>|=</tt>.
- </li><li> The spacing in the examples in this guide is deliberate and part of the
- layout.
</li><li> MACRO names should be in upper case. </li></ul><h2><a name="SECTION00032000000000000000">Module</a></h2> <p> In general, a module is built around a data structure or group of data structures and contains the type definitions (<tt>.h</tt>) and the function prototypes (<tt>.h</tt>) and function definitions (<tt>.c</tt>) for manipulating the types. For a widget module, there may also be a <tt>.uil</tt> file. </p><p> Notes: </p><ul><li> Module names are in lower case (use <tt>_</tt> for separating words). </li></ul><h3><a name="SECTION00032100000000000000"><tt>.h</tt> File</a></h3> <p> </p><pre>/******************************************************************************<br>FILE : <module_name>.h<br><br>LAST MODIFIED : <day> <month as name> <year including century><br><br>DESCRIPTION :<br><A description of what the module is for and what it can do.><br>==============================================================================/<br>#if !defined (<module name in capitals>_H)<br>#define <module name in capitals>_H<br><br>#include <<system includes>><br>#include "<project includes specified relative to project base directory eg.<br> graphics/finite_element.h>"<br><br>/<br>Global types<br>------------<br>/<br><type definitions><br><br>/<br>Global variables<br>----------------<br>/<br><variable declarations. Should all be storage class extern><br><br>/<br>Global functions<br>----------------<br>/<br><prototypes for the functions that can be used by other modules><br>#endif</pre> <p> Notes: </p><ul><li> The section comments should be as shown. </li><li> The spacing between sections should be as shown. </li><li> The ordering of the sections should be as shown. </li></ul><h3><a name="SECTION00032200000000000000"><tt>.c</tt> File</a></h3> <p> </p><pre>/******************************************************************************<br>FILE : <module_name>.c<br><br>LAST MODIFIED : <day> <month as name> <year including century><br><br>DESCRIPTION :<br><A description of what the module is for and what it can do.><br>==============================================================================/<br>#include <<system includes>><br>#include "<project includes specified relative to project base directory eg.<br> graphics/finite_element.h><br><br>/<br>Global variables<br>----------------<br>/<br><variable declarations. Same as in .h except without extern and with<br> initializers><br><br>/<br>Module types<br>------------<br>/<br><declarations for types which are only used within the module. Should be<br> storage class static><br><br>/<br>Module variables<br>----------------<br>/<br><declarations for variables which are global to this module only. Should be<br> storage class static><br><br>/<br>Module functions <br>----------------<br>/<br><definitions for functions which are used in this module only. Should be<br> storage class static><br><br>/<br>Global functions<br>----------------<br>/<br><definitions for the functions prototyped in .h></pre> <p> Notes: </p><ul><li> The section comments should be as shown. </li><li> The spacing between sections should be as shown. </li><li> The ordering of the sections should be as shown. </li></ul><h3><a name="SECTION00032300000000000000"><tt>.uil</tt> File</a></h3> <p> </p><pre>!*******************************************************************************<br>!FILE : <module_name>.uil<br>!<br>!LAST MODIFIED : <day> <month as name> <year including century><br>!<br>!DESCRIPTION :<br>!<A description of what the widgets are for.><br>!===============================================================================<br>module <module_name>_module<br> names=case_sensitive<br><br>procedure<br> <names of the procedures used in the uil code and assigned in the C code. On<br> separate lines><br><br>identifier<br> <names of the identifiers used in the uil code and assigned in the C code. On<br> separate lines><br><br>object<br> <the widget definitions><br><br>end module;</pre> <p> Notes: </p><ul><li> The spacing between sections should be as shown. </li><li> The ordering of the sections should be as shown. </li></ul><h2><a name="SECTION00033000000000000000"><tt>struct</tt> Declaration</a></h2> <p> </p><h3><a name="SECTION00033100000000000000">Top Level</a></h3> <p> </p><pre>struct <Struct_name><br>/******************************************************************************<br>LAST MODIFIED : <day> <month as name> <year including century><br><br>DESCRIPTION :<br><A description of what the type is for.><br>==============================================================================/<br>{<br> <struct body><br>}; /* struct <Struct_name> /</pre> <p> Notes: </p><ul><li> First letter of the structure name is upper case. </li></ul><h3><a name="SECTION00033200000000000000">As a Field</a></h3> <p> </p><pre>struct<br>{<br> <struct body><br>} <field_name>;</pre> <p> Notes: </p><ul><li> First letter of the structure name is lower case. </li></ul><h2><a name="SECTION00034000000000000000"><tt>union</tt> Declaration</a></h2> <p> As for struct, but with struct replaced by union. </p><p> </p><h2><a name="SECTION00035000000000000000"><tt>enum</tt> Declaration</a></h2> <p> </p><pre>enum <Enum_type><br>/*******************************************************************************<br>LAST MODIFIED : <day> <month as name> <year including century><br><br>DESCRIPTION :<br><A description of what the type is for.><br>==============================================================================/<br>{<br> <ENUM_CONSTANTs on separate lines><br>}; /* enum <Enum_type> /</pre> <p> Notes: </p><ul><li> First letter of the structure name is upper case. </li><li> Constants are in upper case. </li></ul><h2><a name="SECTION00036000000000000000">Function Prototype</a></h2> <p> </p><pre><return type> <function_name>(<parameter list>);<br>/*******************************************************************************<br>LAST MODIFIED : <day> <month as name> <year including century><br><br>DESCRIPTION :<br><A description of what the function does and what the parameters are.><br>==============================================================================/</pre> <p> Notes: </p><ul><li> Should be the same (including the comment) as the function header in the
<tt>.c</tt> files apart from the added <tt>;</tt>.
</li></ul><h2><a name="SECTION00037000000000000000">Function Definition</a></h2> <p> </p><pre><return type> <function_name>(<parameter list>)<br>/******************************************************************************<br>LAST MODIFIED : <day> <month as name> <year including century><br><br>DESCRIPTION :<br><A description of what the function does and what the parameters are.><br>==============================================================================/<br>{<br> <variable declarations><br><br> ENTER(function_name);<br> <function body><br> LEAVE;<br><br> return (<return_variable>);<br>} /* <function_name> */</pre> <p> Notes: </p><ul><li> Should be the same (including the comment) as the function header in the
<tt>.h</tt> files apart from the added <tt>;</tt> in the <tt>.h</tt> file.
</li><li> Notice the use of the ENTER and LEAVE macros. </li></ul><h2><a name="SECTION00038000000000000000">Variable Declarations</a></h2> <p> </p><pre>int anatomical_list_length,coordinate_list_length,field_list_length,i;<br>struct FE_node_field *node_field_1,*node_field_2;<br>struct FE_node_field_component *component_1,*component_2;<br>struct FE_node_field_info *field_info;<br>struct FE_node_field_info_list_item *item;<br>struct FE_node_field_list_item *node_field_item;</pre> <p> </p><h2><a name="SECTION00039000000000000000"><tt>if</tt> Statement</a></h2> <p> </p><pre>if (<condition>)<br>{<br> <then clause><br>}<br>else<br>{<br> <else clause><br>}</pre> <p> Notes: </p><ul><li> The <tt>{</tt> and <tt>}</tt> are always present, even if there is
only one statement in the clause.
</li><li> The else clause is optional. </li></ul><h2><a name="SECTION000310000000000000000"><tt>do</tt> Statement</a></h2> <p> </p><pre>do<br>{<br> <do body><br>} while (<condition>);</pre> <p> Notes: </p><ul><li> The <tt>{</tt> and <tt>}</tt> are always present, even if there is
only one statement in the clause.
</li></ul><h2><a name="SECTION000311000000000000000"><tt>while</tt> Statement</a></h2> <p> </p><pre>while (<condition>)<br>{<br> <while body><br>}</pre> <p> Notes: </p><ul><li> If there are one or more statements in the body then the <tt>{</tt>
and <tt>}</tt> should be used. If there are no statements in the body then <tt>while (<condition>);</tt> should be used.
</li></ul><h2><a name="SECTION000312000000000000000"><tt>for</tt> Statement</a></h2> <p> </p><pre>for (<initialize>;<terminate>;<update>)<br>{<br> <for body><br>}</pre> <p> Notes: </p><ul><li> The <tt>{</tt> and <tt>}</tt> are always present, even if there is
only one statement in the clause.
</li></ul><h2><a name="SECTION000313000000000000000"><tt>switch</tt> Statement</a></h2> <p> </p><pre>switch (<expression>)<br>{<br> case <case_label1>: case <case_label2>:<br> {<br> <case clause><br> } break;<br> default:<br> {<br> <default clause><br> } break;<br>}</pre> <p> Notes: </p><ul><li> The <tt>{</tt> and <tt>}</tt> are always present, even if there is
only one statement in the clause.
</li><li> The <tt>break</tt>s should always be used. </li></ul><h2><a name="SECTION000314000000000000000">Debug Statements</a></h2> <p> Debug statements should be preceded by the comment </p><pre>/???debug */</pre> and the indentation should be restarted in column 1. <p> </p><h2><a name="SECTION000315000000000000000">Comments</a></h2> <p> Apart from the special comments shown above, all comments should be on separate lines and be indented at the current level of indentation. Temporary comments querying existing code or suggesting enhancements should be of the form </p><pre>/???<programmer identification> . <text> */</pre> <p> </p><h1><a name="SECTION00040000000000000000">Style</a></h1> <p> </p><h2><a name="SECTION00041000000000000000">return</a></h2> <p> The <tt>return</tt> statement should only ever be the last statement in a function. There should be at most one <tt>return</tt> statement per function. </p><p> </p><h2><a name="SECTION00042000000000000000"><tt>exit</tt></a></h2> <p> The <tt>exit</tt> statement should not be used. </p><p> </p><h2><a name="SECTION00043000000000000000"><tt>break</tt></a></h2> <p> The <tt>break</tt> statement should only be used to end clauses in a <tt>switch</tt> statement (see above). </p><p> </p><h2><a name="SECTION00044000000000000000"><tt>continue</tt></a></h2> <p> The <tt>continue</tt> statement should not be used. </p><p> </p><h2><a name="SECTION00045000000000000000"><tt>goto</tt></a></h2> <p> <tt>goto</tt> should not be used. </p><p> </p><h2><a name="SECTION00046000000000000000"><tt>elseif</tt></a></h2> <p> <tt>elseif</tt> should not be used. </p><p> </p><h2><a name="SECTION00047000000000000000"><tt>typedef</tt></a></h2> <p> <tt>typedef</tt> should not be used for <tt>struct</tt>'s, <tt>union</tt>'s or <tt>enum</tt>'s. </p><p> </p><h2><a name="SECTION00048000000000000000">Memory Allocation</a></h2> <p> The macros <tt>ALLOCATE</tt> and <tt>DEALLOCATE</tt> (in <tt>general/debug.h</tt>) should be used for all memory allocation and deallocation (no <tt>malloc</tt> or <tt>free</tt>). </p><p> </p><h2><a name="SECTION00049000000000000000"><tt>ENTER</tt> and <tt>LEAVE</tt> (in <tt>general/debug.h</tt>)</a></h2> <p> <tt>ENTER</tt> should be the first statement and <tt>LEAVE</tt> should be the second to last or last (if no <tt>return</tt>) statement in every function. </p><p> </p><h2><a name="SECTION000410000000000000000">Comments</a></h2> <p> Comments should be factual, and should only attempt humour if they are bloody funny. </p><p> </p><h2><a name="SECTION000411000000000000000">Clarity</a></h2> <p> Code should not be obscure. One tactic to help achieve this is to only do one thing per statement, <em>e.g.,</em> </p><pre>ai=b;<br>i++;</pre> instead of <pre>ai++=b;</pre> <p> </p><h2><a name="SECTION000412000000000000000">Lists</a></h2> <p> Macros have been written (<tt>graphics/list.h</tt>) for creating and using lists. These macros should be used for all lists. </p><p> </p><h2><a name="SECTION000413000000000000000">Casting <tt>NULL</tt></a></h2> <p> <tt>NULL</tt> should always be caste to the appropriate type. </p> <h2>Using reference counting</h2> <p> Reference counting should be carried out using the macros ACCESS, DEACCESS, and REACCESS on objects that need it. When this is done, the following rules apply: <ul>
<li>Before storing a pointer into a structure, ACCESS the pointer.</li> <li>DEACCESS when nulling out a pointer.</li> <li>Set the access count to zero in CREATE. ACCESS is then required after CREATE.</li>
</ul> </p>