[m-dev.] for review: update c_coding_guidelines.html

[Fergus Henderson]

Hi,

Do these changes look OK?

----------

Estimated hours taken: 0.75

w3/information/developers/c_coding_standard.html:
	- Change the recommended order of declarations in
	  header files: `#defines' should in general come
	  last, after function declarations, rather than before
	  type definitions.
	- Say that macros should be documented.
	- Document the convention of appending `_Struct'
	  for struct names.
	- Update the pointers to documentation on memory management.
	- Do not require all files to be licensed under the GPL.

Workspace: /home/mercury0/fjh/mercury
Index: w3/information/developers/c_coding_standard.html
===================================================================
RCS file: /home/mercury1/repository/w3/information/developers/c_coding_standard.html,v
retrieving revision 1.1
diff -u -d -r1.1 c_coding_standard.html
--- c_coding_standard.html	1998/09/04 05:01:54	1.1
+++ c_coding_standard.html	1999/12/29 11:25:29
@@ -87,7 +87,7 @@
 <h4>
 1.2.1. Source files</h4>
 
-Items in source files should be in this order:
+Items in source files should in general be in this order:
 <ul>
 <li>	Prologue comment describing the module.
 <li>	#includes of system headers (such as stdio.h and unistd.h)
@@ -104,12 +104,12 @@
 <h4>
 1.2.2. Header files</h4>
 
-Items in headers should be in this order:
+Items in headers should in general be in this order:
 <ul>
-<li>	#defines 
 <li>	typedefs, structs, unions, enums
 <li>	extern variable declarations
 <li>	function prototypes
+<li>	#defines 
 </ul>
 
 Note also that every header should be protected against multiple inclusion
@@ -147,14 +147,20 @@
 <p>
 Note: memory allocation for C code that must interface
 with Mercury code or the Mercury runtime should be
-done according to the documentation in mercury/runtime/heap.h
-and the Mercury User's Guide and Mercury Language Reference Manual.
-<font color="#ff0000">
-XXX: Currently none of these say anything about it, though.
-<font color="#000000">
+done using the routines defined and documented in
+mercury/runtime/mercury_memory.h and/or mercury/runtime/heap.h,
+according to the documentation in those files,
+in mercury/trace/README, and in the Mercury Language Reference Manual.
 
 <h4>
-2.1.2. Headers</h4>
+2.1.2. Macros</h4>
+
+Each non-trivial macro should be documented just as for functions (see above).
+It is also a good idea to document the types of macro arguments and
+return values, e.g. by including a function declaration in a comment.
+
+<h4>
+2.1.3. Headers</h4>
 
 Such function comments should be present in header files for each function
 exported from a source file. Ideally, a client of the module should 
@@ -163,19 +169,19 @@
 working out how an exported function works.
 
 <h4>
-2.1.3. Source files</h4>
+2.1.4. Source files</h4>
 
 Every source file should have a prologue comment which includes:
 <ul>
 <li>	Copyright notice.
-<li>	GNU Public Licence info.
+<li>	Licence info (e.g. GPL or LGPL).
 <li>	Short description of the purpose of the module.
 <li>	Any design information or other details required to understand
 	and maintain the module.
 </ul>
 
 <h4>
-2.1.4. Global variables</h4>
+2.1.5. Global variables</h4>
 
 Any global variable should be excruciatingly documented. This is
 especially true when globals are exported from a module.
@@ -183,7 +189,7 @@
 a global. 
 
 <h3>
-2.1. Comment style</h3>
+2.2. Comment style</h3>
 
 Use comments of this form:
 <font color="#0000ff">
@@ -202,10 +208,10 @@
 <font color="#000000">
 
 <h3>
-2.2. Guidelines for comments</h3>
+2.3. Guidelines for comments</h3>
 
-<h3>
-2.3. Revisits</h3>
+<h4>
+2.3.1. Revisits</h4>
 
 Any code that needs to be revisited because it is a temporary hack
 (or some other expediency) must have a comment of the form:
@@ -221,8 +227,8 @@
 that can be understood by developers other than the author of the
 comment.
 
-<h3>
-2.4. Comments on preprocessor statements</h3>
+<h4>
+2.3.2. Comments on preprocessor statements</h4>
 
 The <tt>#ifdef</tt> constructs should 
 be commented like so if they extend for more than a few lines of code:
@@ -296,7 +302,7 @@
 For instance, <tt>soul_machine</tt>.
 
 <h3>
-4.2. Enums, macros and #define constants</h3>
+4.2. Enumeration constants, macros and #define constants</h3>
 
 Use all uppercase with underscores to separate words.
 For instance, <tt>MAX_HEADROOM</tt>.
@@ -309,7 +315,23 @@
 For instance, <tt>Directory_Entry</tt>.
 
 <h3>
-4.4. Mercury specifics </h3>
+4.4. Structs and unions</h3>
+
+If something is both a struct and a typedef, the
+name for the struct should be formed by appending `_Struct'
+to the typedef name:
+<font color="#0000ff">
+<pre>
+	typedef struct Directory_Entry_Struct {
+		...
+	} DirectoryEntry;
+</pre>
+<font color="#000000">
+
+For unions, append `_Union' to the typedef name.
+
+<h3>
+4.5. Mercury specifics </h3>
 
 For anything exported from mercury/runtime, prefix it with MR_.
 For anything exported from mercury/library, prefix it with ML_.

-- 
Fergus Henderson <fjh at cs.mu.oz.au>  |  "I have always known that the pursuit
WWW: <http://www.cs.mu.oz.au/~fjh>  |  of excellence is a lethal habit"
PGP: finger fjh at 128.250.37.3        |     -- the last words of T. S. Garp.
--------------------------------------------------------------------------
mercury-developers mailing list
Post messages to:       mercury-developers at cs.mu.oz.au
Administrative Queries: owner-mercury-developers at cs.mu.oz.au
Subscriptions:          mercury-developers-request at cs.mu.oz.au
--------------------------------------------------------------------------