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

[Fergus Henderson]

On 29-Dec-1999, schachte at cs.mu.OZ.AU <schachte at cs.mu.OZ.AU> wrote:
> On 29 Dec, Fergus Henderson wrote:
> 
> > 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.
> 
> It would be good to have some rationale for the recommended ordering. 
...
The main rationale for changing it was that the order specified
in the coding standard did not match the order that we were
actually using.  In particular, I had a look through the
header files, and in most cases of header files containing both
typedefs and macros, the typedefs came first.
Generally we define the type first, and then the operations
on that type.

> I'm curious:  why put #defines after function declarations?

There's not that many headers in the Mercury runtime which contain
both macros and function declarations, and the ordering there
is not consistent, so the past precedent with regard to relative
ordering of macros and function declarations is not so clear.

> The other
> order, or mixed order, would seem better, since it allows function
> declarations to make use of macros (not often useful, but occasionally
> so); of course macro definitions can use functions either way.

I think it depends on the kind of macro.
Function-like macros are basically just alternatives to inline
function definitions; for these, it makes sense to put them with
function declarations.

On the other hand, some macros, e.g. constants specifying array
bounds, may need to precede even the type definitions.  We tend to
avoid using fixed limits, so we don't have to many of those.

Probably the coding guidelines should explain this in a bit
more detail than they currently do.

-- 
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
--------------------------------------------------------------------------