C coding standard changes

[Bert Thompson]

Fergus,

I've made the appropriate changes and made a couple of comments
on your message.

The context diff is at the end of this mail.

(Apologies for taking a while to get back to you, but I'm working on
the Nude paper still. I'll soon by able to put that behind me, BTW.)

Bert

|Bert Thompson, you wrote:
|> 
|> I think the best option is to list
|> what tools we are allowed to depend on. It makes sense to limit us 
|> to using only some -essential- POSIX utilities. This is one of the
|> most important parts of the coding standard, IMHO.[1] Do we -really- 
|> need Perl and GNU make, for example? 
|
|Perl is needed for texi2html.  GNU Make is needed for `include',
|`VPATH', and pattern rules; it is not easy to work around the lack of
|these features.
|
|> Anyway, here's my ideal list for tools required:
|> 	- Bourne shell (or POSIX shell, which subsumes Bourne shell)
|> 	- make
|> 	- ANSI C compiler (or GNU C, if available)
|> 	- POSIX C libraries
|
|I'd add the following:
|
|For running Mercury: the above, plus
|
|	cat, cp, mv, ln, rm, mkdir, rmdir
|	echo, test, true, false, expr, basename, dirname
|	head, tail, sed, awk, grep/fgrep/egrep, xargs[*]
|
|Additional dependencies are OK if (a) they are for non-core functionality
|and (b) they would be too hard to implement using only the tools above.
|Currently there are the following additional dependencies:
|
|	`pragma fact_table' requires sort and uniq
|
|	mtags requires perl
|
|	Prolog support requires NU-Prolog or SICStus Prolog
|
|	mmake requires a version of `make' that supports VPATH
|		(actually that is a bad example, since mmake
|		is really part of the "core" functionality;
|		but there is no easy work-around)
|
|For installing Mercury: the basic stuff required for running Mercury, plus
|
|	tar, gzip[*]
|	GNU Make[*]
|
|[*] It's a pity we need xargs, gzip, and GNU Make, since they're not
|really standard, but there is no easy work-around.  I think all the
|others are standard POSIX utilities.
|
|For maintaining Mercury: the above, plus
|
|	autoconf
|	cvs
|	texinfo, tex, perl
|
|Can you please put the above lists in the coding standard, and
|add a note saying that any new dependencies should be documented
|there too?

Done.

|Actually, I'm not sure whether the coding standard is the right place to
|document this stuff -- perhaps it should be documented in a
|separate file.

I think it is. No-one would ever bother to look at a separate file
containing only that info. True, it's not really C coding per se, 
but does come under development.


------------------------------------------------------------


Index: c_coding_standard.html
===================================================================
RCS file: /home/staff/zs/imp/www/developer/c_coding_standard.html,v
retrieving revision 1.2
diff -c -r1.2 c_coding_standard.html
*** 1.2	1997/02/14 06:15:06
--- c_coding_standard.html	1997/03/06 10:38:16
***************
*** 26,32 ****
  
  Because the coding standard has been kept deliberately brief, there are
  some items missing that would be included in a more comprehensive 
! coding standard. For more on commonsense C programming, you may
  consult the <a href="ftp://ftp.cs.toronto.edu/doc/programming/ihstyle.ps">
  Indian Hill C coding standard </a> or the 
  <a href="http://www.eskimo.com/~scs/C-faq/top.html">
--- 26,32 ----
  
  Because the coding standard has been kept deliberately brief, there are
  some items missing that would be included in a more comprehensive 
! standard. For more on commonsense C programming, 
  consult the <a href="ftp://ftp.cs.toronto.edu/doc/programming/ihstyle.ps">
  Indian Hill C coding standard </a> or the 
  <a href="http://www.eskimo.com/~scs/C-faq/top.html">
***************
*** 33,44 ****
  comp.lang.c FAQ</a>. <p>
  
  <h2>
! 1. File Organization</h2>
  
  <h3>
! 1.1. Modules and Interfaces</h3>
  
! We impose a discipline on C to allow us to (poorly) emulate the modules
  of languages such as Ada and Modula-3.
  <ul>
  <li>	Every .c file has a corresponding .h file with the
--- 33,44 ----
  comp.lang.c FAQ</a>. <p>
  
  <h2>
! 1. File organization</h2>
  
  <h3>
! 1.1. Modules and interfaces</h3>
  
! We impose a discipline on C to allow us to emulate (poorly) the modules
  of languages such as Ada and Modula-3.
  <ul>
  <li>	Every .c file has a corresponding .h file with the
***************
*** 49,67 ****
  	just use the terms `source file' and `header'.
  
  <li>	All items exported from a source file must be declared in
! 	the header. Items includes functions, variables, #defines,
! 	typedefs, enums, structs, and so on. Anything that doesn't 
! 	allocate storage. Don't bother qualifying function prototypes with
! 	the `extern' keyword. Do qualify variable declarations
  	with the `extern' keyword, otherwise storage for the
  	variable will be allocated in every source file that
  	includes the header containing the variable definition.
  
! <li>	We import a module by including it's header.
  	Never give extern declarations for imported
! 	functions. Always include it's header.
  
! <li>	Headers must #include any other header on which it depends.
  	Hence it's imperative every header be protected against multiple
  	inclusion. Also, take care to avoid circular dependencies.
  
--- 49,69 ----
  	just use the terms `source file' and `header'.
  
  <li>	All items exported from a source file must be declared in
! 	the header. These items include functions, variables, #defines,
! 	typedefs, enums, structs, and so on. In short, an item is anything 
! 	that doesn't allocate storage. 
! 	Qualify function prototypes with the `extern' keyword.
! 	Also, do qualify each variable declaration
  	with the `extern' keyword, otherwise storage for the
  	variable will be allocated in every source file that
  	includes the header containing the variable definition.
  
! <li>	We import a module by including its header.
  	Never give extern declarations for imported
! 	functions in source files. Always include the header of the
! 	module instead.
  
! <li>	Each header must #include any other headers on which it depends.
  	Hence it's imperative every header be protected against multiple
  	inclusion. Also, take care to avoid circular dependencies.
  
***************
*** 80,86 ****
  </ul>
  
  <h3>
! 1.2. Organization Within A File</h3>
  
  <h4>
  1.2.1. Source files</h4>
--- 82,88 ----
  </ul>
  
  <h3>
! 1.2. Organization within a file</h3>
  
  <h4>
  1.2.1. Source files</h4>
***************
*** 93,101 ****
  	for technical reasons, <font color="#0000ff">imp.h<font color=#000000">
  	must be the first #include.
  <li>	Any local #defines.
! <li>	Definitions of any local (that is, file-static) global variables
! <li>	Prototypes for any local (that is, file-static) functions
! <li>	Definitions of functions
  </ul>
  
  <h4>
--- 95,103 ----
  	for technical reasons, <font color="#0000ff">imp.h<font color=#000000">
  	must be the first #include.
  <li>	Any local #defines.
! <li>	Definitions of any local (that is, file-static) global variables.
! <li>	Prototypes for any local (that is, file-static) functions.
! <li>	Definitions of functions.
  </ul>
  
  <h4>
***************
*** 103,109 ****
  
  Items in headers should be in this order:
  <ul>
! <li>	#defines, typedefs, structs, unions, enums
  <li>	extern variable declarations
  <li>	function prototypes
  </ul>
--- 105,112 ----
  
  Items in headers should be in this order:
  <ul>
! <li>	#defines 
! <li>	typedefs, structs, unions, enums
  <li>	extern variable declarations
  <li>	function prototypes
  </ul>
***************
*** 153,161 ****
  2.1.2. Headers</h4>
  
  Such function comments should be present in header files for each function
! exported from a source file. Ideally, in OO terminology, a 
! client of the module should not have to look at the implementation, 
! only the interface. In C terminology, the header should suffice for
  working out how an exported function works.
  
  <h4>
--- 156,164 ----
  2.1.2. 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 
! not have to look at the implementation, only the interface. 
! In C terminology, the header should suffice for
  working out how an exported function works.
  
  <h4>
***************
*** 163,169 ****
  
  Every source file should have a prologue comment which includes:
  <ul>
! <li>	Copyright of Melbourne Uni .
  <li>	GNU Public Licence info.
  <li>	Short description of the purpose of the module.
  <li>	Any design information or other details required to understand
--- 166,172 ----
  
  Every source file should have a prologue comment which includes:
  <ul>
! <li>	Copyright notice.
  <li>	GNU Public Licence info.
  <li>	Short description of the purpose of the module.
  <li>	Any design information or other details required to understand
***************
*** 198,204 ****
  <font color="#000000">
  
  <h3>
! 2.2. Guidelines for Comments</h3>
  
  <h3>
  2.3. Revisits</h3>
--- 201,207 ----
  <font color="#000000">
  
  <h3>
! 2.2. Guidelines for comments</h3>
  
  <h3>
  2.3. Revisits</h3>
***************
*** 274,280 ****
  3.2. Static and extern declarations</h3>
  
  Limit module exports to the absolute essentials. Make as much static
! as possible since this keeps interfaces to modules simpler.
  
  <h3>
  3.3. Typedefs</h3>
--- 277,283 ----
  3.2. Static and extern declarations</h3>
  
  Limit module exports to the absolute essentials. Make as much static
! (that is, local) as possible since this keeps interfaces to modules simpler.
  
  <h3>
  3.3. Typedefs</h3>
***************
*** 283,289 ****
  useful on structs, unions, and enums.
  
  <h2>
! 4. Naming Conventions</h2>
  
  <h3>
  4.1. Function and variable names</h3>
--- 286,292 ----
  useful on structs, unions, and enums.
  
  <h2>
! 4. Naming conventions</h2>
  
  <h3>
  4.1. Function and variable names</h3>
***************
*** 292,304 ****
  For instance, <tt>soul_machine</tt>.
  
  <h3>
! 4.2. #define constants, macros, and enums</h3>
  
  Use all uppercase with underscores to separate words.
  For instance, <tt>MAX_HEADROOM</tt>.
  
  <h3>
! 4.3. typedefs</h3>
  
  Use first letter uppercase for each word, other letters lowercase and
  underscores to separate words.
--- 295,307 ----
  For instance, <tt>soul_machine</tt>.
  
  <h3>
! 4.2. Enums, macros and #define constants</h3>
  
  Use all uppercase with underscores to separate words.
  For instance, <tt>MAX_HEADROOM</tt>.
  
  <h3>
! 4.3. Typedefs</h3>
  
  Use first letter uppercase for each word, other letters lowercase and
  underscores to separate words.
***************
*** 311,322 ****
  For anything exported from mercury/library, prefix it with ML_.
  
  <h2>
! 5. Syntax and Layout</h2>
  
  <h3>
  5.1. Minutiae</h3>
  
! Use 8 spaces to a tab. No line shall be longer than 79 characters.
  If a statement is too long, continue it on the next line <em>indented 
  two levels deeper</em>. If the statement extends over more than two
  lines, then make sure the subsequent lines are indented to the
--- 314,325 ----
  For anything exported from mercury/library, prefix it with ML_.
  
  <h2>
! 5. Syntax and layout</h2>
  
  <h3>
  5.1. Minutiae</h3>
  
! Use 8 spaces to a tab. No line should be longer than 79 characters.
  If a statement is too long, continue it on the next line <em>indented 
  two levels deeper</em>. If the statement extends over more than two
  lines, then make sure the subsequent lines are indented to the
***************
*** 472,478 ****
  <h4>
  5.3.1. Nesting</h4>
  
! Nested #ifdefs and #ifndefs should be indented by two spaces for
  each level of nesting. For example:
  
  <font color="#0000ff">
--- 475,481 ----
  <h4>
  5.3.1. Nesting</h4>
  
! Nested #ifdefs, #ifndefs and #ifs should be indented by two spaces for
  each level of nesting. For example:
  
  <font color="#0000ff">
***************
*** 491,499 ****
  <h2>
  6. Portability</h2>
  
! <font color="#ff0000">
! This section is yet to be written.
! <font color="#000000">
  
  <h2>
  7. Coding specifics</h2>
--- 494,606 ----
  <h2>
  6. Portability</h2>
  
! <h3>
! 6.1. Architecture specifics</h3>
! 
! Avoid relying on properties of a specific machine architecture unless
! necessary, and if necessary localise such dependencies. Having architecture-
! specific macros to hide access to machine-dependent code is one solution.
! 
! Some machine-specific properties are:
! <ul>
! <li>	Size (in bits) of C builtin datatypes (short, int, long, float, 
! 	double).
! <li>	Byte-order. Big- or little-endian (or other).
! <li>	Alignment requirements.
! </ul>
! 
! <h3>
! 6.2. Operating system specifics</h3>
! 
! Operating system APIs differ from platform to platform. Although 
! most support standard POSIX calls such as `read', `write'
! and `unlink', you cannot rely on the presence of, for instance, 
! System V shared memory, or BSD sockets.
! <p>
! Adhere to POSIX-supported operating system calls whenever possible
! since they are widely supported, even by Windows and VMS.
! <p>
! When POSIX doesn't provide the required functionality, ensure that
! the operating system specific calls are localised. 
! 
! <h3>
! 6.3. Compiler and C library specifics</h3>
! 
! ANSI C compilers are now widespread and hence we needn't pander to
! old K&R compilers. However compilers (in particular the GNU C compiler)
! often provide non-ANSI extensions. Ensure that any use of compiler
! extensions is localised and protected by #ifdefs.
! <p>
! Don't rely on features whose behaviour is undefined according to
! the ANSI C standard. For that matter, don't rely on C arcana 
! even if they <em>are</em> defined. For instance, 
! <tt>setjmp/longjmp</tt> and ANSI signals often have subtle differences
! in behaviour between platforms.
! <p>
! If you write threaded code, make sure any non-reentrant code is
! appropriately protected via mutual exclusion. The biggest cause
! of non-reentrant (non-thread-safe) code is function-static data.
! Note that some C library functions may be non-reentrant. This may
! or may not be documented in the man pages.
! 
! <h3>
! 6.4. Environment specifics</h3>
! 
! This is one of the most important sections in the coding standard.
! Here we mention what other tools Mercury depends on.
! Mercury <em>must</em> depend on some tools, however every tool that
! is needed to use Mercury reduces the potential user base.
! <p>
! That is worth repeating: <br>
! EVERY EXTRA DEPENDENCY IS ANOTHER BITE OUT OF THE USER BASE.
! <p>
! Bear that in mind when tempted to add YetAnotherTool<sup>TM</sup>.
! 
! <h4>
! 6.4.1. Tools required for Mercury</h4>
! 
! In order to build the Mercury compiler, you need:
! <ul>
! <li>	A shell compatible with Bourne shell (sh)
! <li>	gzip
! <li>	tar
! <li>	GNU make
! <li>	One of:
! 	<ul>
! 	<li>	The GNU C compiler
! 	<li>	Any ANSI C compiler
! 	</ul>
! <li>	Perl <font color="#ff0000">XXX: Which version?<font color="#000000">
! <li>	Various POSIX utilities: <br>
! 	awk basename cat cp dirname echo egrep expr false fgrep grep head 
! 	ln mkdir mv rmdir rm sed sort tail test true uniq xargs
! </ul>
! 
! <p>
! 
! In order to modify and maintain the source code of the Mercury compiler,
! you also need:
! <ul>
! <li>	CVS
! <li>	autoconf
! <li>	texinfo
! <li>	TeX
! </ul>
! 
! <p>
! 
! For Prolog support, you need one of:
! <ul>
! <li>	A NU-Prolog installation
! <li>	A SICStus Prolog installation
! </ul>
! 
! <h4>
! 6.4.2. Documenting the tools</h4>
! 
! If further tools are required, you should add them to the above list.
! And similarly, if you eliminate dependence on a tool, remove
! it from the above list.
  
  <h2>
  7. Coding specifics</h2>