</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 : &lt;module_name&gt;.h<br><br>LAST MODIFIED : &lt;day&gt; &lt;month as name&gt; &lt;year including century&gt;<br><br>DESCRIPTION :<br>&lt;A description of what the module is for and what it can do.&gt;<br>==============================================================================/<br>#if !defined (&lt;module name in capitals&gt;_H)<br>#define &lt;module name in capitals&gt;_H<br><br>#include &lt;&lt;system includes&gt;&gt;<br>#include "&lt;project includes specified relative to project base directory eg.<br> graphics/finite_element.h&gt;"<br><br>/<br>Global types<br>------------<br>/<br>&lt;type definitions&gt;<br><br>/<br>Global variables<br>----------------<br>/<br>&lt;variable declarations. Should all be storage class extern&gt;<br><br>/<br>Global functions<br>----------------<br>/<br>&lt;prototypes for the functions that can be used by other modules&gt;<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 : &lt;module_name&gt;.c<br><br>LAST MODIFIED : &lt;day&gt; &lt;month as name&gt; &lt;year including century&gt;<br><br>DESCRIPTION :<br>&lt;A description of what the module is for and what it can do.&gt;<br>==============================================================================/<br>#include &lt;&lt;system includes&gt;&gt;<br>#include "&lt;project includes specified relative to project base directory eg.<br> graphics/finite_element.h&gt;<br><br>/<br>Global variables<br>----------------<br>/<br>&lt;variable declarations. Same as in .h except without extern and with<br> initializers&gt;<br><br>/<br>Module types<br>------------<br>/<br>&lt;declarations for types which are only used within the module. Should be<br> storage class static&gt;<br><br>/<br>Module variables<br>----------------<br>/<br>&lt;declarations for variables which are global to this module only. Should be<br> storage class static&gt;<br><br>/<br>Module functions <br>----------------<br>/<br>&lt;definitions for functions which are used in this module only. Should be<br> storage class static&gt;<br><br>/<br>Global functions<br>----------------<br>/<br>&lt;definitions for the functions prototyped in .h&gt;</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 : &lt;module_name&gt;.uil<br>!<br>!LAST MODIFIED : &lt;day&gt; &lt;month as name&gt; &lt;year including century&gt;<br>!<br>!DESCRIPTION :<br>!&lt;A description of what the widgets are for.&gt;<br>!===============================================================================<br>module &lt;module_name&gt;_module<br> names=case_sensitive<br><br>procedure<br> &lt;names of the procedures used in the uil code and assigned in the C code. On<br> separate lines&gt;<br><br>identifier<br> &lt;names of the identifiers used in the uil code and assigned in the C code. On<br> separate lines&gt;<br><br>object<br> &lt;the widget definitions&gt;<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 &lt;Struct_name&gt;<br>/******************************************************************************<br>LAST MODIFIED : &lt;day&gt; &lt;month as name&gt; &lt;year including century&gt;<br><br>DESCRIPTION :<br>&lt;A description of what the type is for.&gt;<br>==============================================================================/<br>{<br> &lt;struct body&gt;<br>}; /* struct &lt;Struct_name&gt; /</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> &lt;struct body&gt;<br>} &lt;field_name&gt;;</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 &lt;Enum_type&gt;<br>/*******************************************************************************<br>LAST MODIFIED : &lt;day&gt; &lt;month as name&gt; &lt;year including century&gt;<br><br>DESCRIPTION :<br>&lt;A description of what the type is for.&gt;<br>==============================================================================/<br>{<br> &lt;ENUM_CONSTANTs on separate lines&gt;<br>}; /* enum &lt;Enum_type&gt; /</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>&lt;return type&gt; &lt;function_name&gt;(&lt;parameter list&gt;);<br>/*******************************************************************************<br>LAST MODIFIED : &lt;day&gt; &lt;month as name&gt; &lt;year including century&gt;<br><br>DESCRIPTION :<br>&lt;A description of what the function does and what the parameters are.&gt;<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>&lt;return type&gt; &lt;function_name&gt;(&lt;parameter list&gt;)<br>/******************************************************************************<br>LAST MODIFIED : &lt;day&gt; &lt;month as name&gt; &lt;year including century&gt;<br><br>DESCRIPTION :<br>&lt;A description of what the function does and what the parameters are.&gt;<br>==============================================================================/<br>{<br> &lt;variable declarations&gt;<br><br> ENTER(function_name);<br> &lt;function body&gt;<br> LEAVE;<br><br> return (&lt;return_variable&gt;);<br>} /* &lt;function_name&gt; */</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> The else clause is optional.
</li></ul><h2><a name="SECTION000310000000000000000"><tt>do</tt> Statement</a></h2>
<p>
</p><pre>do<br>{<br> &lt;do body&gt;<br>} while (&lt;condition&gt;);</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 (&lt;condition&gt;)<br>{<br> &lt;while body&gt;<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 (&lt;condition&gt;);</tt> should be used.

</li></ul><h2><a name="SECTION000312000000000000000"><tt>for</tt> Statement</a></h2>
<p>
</p><pre>for (&lt;initialize&gt;;&lt;terminate&gt;;&lt;update&gt;)<br>{<br> &lt;for body&gt;<br>}</pre>
<p>
Notes:
</p><ul><li> The <tt>{</tt> and <tt>}</tt> are always present, even if there is

</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>/???&lt;programmer identification&gt; . &lt;text&gt; */</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>