From: mueller@b30news.b30.ingr.com ( Phil Mueller )
Subject: Re: C Code Layout [long]
Organization: Intergraph
Date: Tue, 15 Dec 1992 13:06:15 GMT

In article <1992Dec7.223748.26505@fcom.cc.utah.edu> bryant@ced.utah.edu writes:
>In article 6312@b30.ingr.com, mueller@b30news.b30.ingr.com ( Phil Mueller ) writes:
>>
>> ... I put the function and paramter declaration in the header itself:
>>
>><include files>
>>
>>/* NC NC NC NC NC NC NC NC NC NC NC NC NC NC NC NC NC NC NC NC NC NC NC NC */
>>
>>int function0( arg0, arg1, arg2, arg3, arg4 )
>>int             arg0;   /* i    one-line description of arg0 */
>>int             *arg1;  /* [i]  one-line blah blah blah      */
>>TYPEXYZZY       *arg2;  /* io   arg2 is  */
>>TYPEAGAIN       *arg3;  /* o    arg3 is */
>>double          *arg4;  /* [o]  arg4 is */
>>
>>/* 
>>DESCRIPTION
>>  this function does blah blah blah
>>  blah blah blah
>>  Any further decription of the arguments also go here.
>>
>>HISTORY
>>       Author     Date          Description
>>       -----      ----          -----------
>>        pam     12/07/91        initial spec
>>        moh     12/18/91        made arg1 optional
>>        xac     06/22/92        correct something TR 92w1234
>>
>>NC NC NC NC NC NC NC NC NC NC NC NC NC NC NC NC NC NC NC NC NC NC NC NC NC */
>>
>
>I was resisting, but now I must put in my thoughts on this. I may
>stand alone, but I RESIST the idea of putting a large comment block
>between the declaration of the function and the code of that function.
>There is something to be said for having as much code together as
>possible.
>
>Here is an example of a complete file produced where I work. We
>use RCS and have extraction programs to automatically extract
>documentation (LaTeX) from the source and headers. Comments are
>welcome!
>
>/*File
> *  $RCSfile$
> *  $Revision$
> *  $Author$, $State$, $Locker$
> *  Program : 
> *  Project : 
> *
> *  $Log$
> *  Copyright 1991 by the Center for Engineering Design and
> *    the University of Utah.  All rights reserved.
> *
> *~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
> *
> *  Description :
> *    
> *
> *  Compile Flags :
> *    flag ; description.
> *
> *  Routines :
> *    name
> *
> *  Assumptions :
> *    description.
> *
> *****************************************************************************/
>
>/* Local Definitions. */
>
>/* System Header Files. */
>
>/* Lab Header Files. */
>
>/* Project Header Files. */
>
>/* Local Header Files. */
>
>/* Local Type Declarations. */
>
>/* Local Function Prototypes. */
>
>/* Global Variable Declarations. */
>
>/* Local Variable Declarations. */
>
>static char
>  *rcs_ident() { return "$Header:$"; }
>
>
>/*
> *  Code for local functions.
> */
>
>
>/*
> *  Code for exported functions.
> */
>
>/*Function*********************************************************************
> *
> *  Name : 
> *  Date : 
> *
> *  Description :
> *    ONE LINE DESCRIPTION.
> *  Side Effects : (optional)
> *    VERY SPECIFIC EXTERNAL SIDE EFFECTS.
> *
> *  Parameters :
> *    type name ; WHAT DOES IT MEAN.
> *  Return Value :
> *    type ; MEANING.
> *
> *  Algorithm : (optional)
> *    DETAILED DESCRIPTION. SHOULD READ LIKE CODE.
> *
> *  Dependencies : (optional)
> *    ASSUMPTIONS MADE IN THE CODE. THINGS THAT COULD CAUSE IT NOT TO WORK.
> *
> *  See Also : (optional)
> *    ROUTINES, MANUALS, MAN PAGES, PAPER DOCUMENTATION.
> *
> *  Known Bugs : (optional)
> *    ANY PROBLEM NOTED WITH THE CODE THAT SHOULD BE FIXED IN TIME.
> *
> *****************************************************************************/
>
>/* End file. */
>
>

When I started programming for a living, I put the parameters as comments
separated from the actual declaration.  The *first* time I added a parameter
to a function, I neglected to add it to the comments.  I tried to use the 
function, got the arg list wrong, and crashed.  I decided to put the
actual declaration in the header.

>We do not keep track of authorship and all history is kept via the
>RPC checkin logs.
>
>The order of include files, type declarations, etc. is important and
>was done to maximize the number of warnings or errors caused by
>scoping violations.
>
>All templates are inserted automatically upon file creation (we use
>Emacs), we have templates for C and C++, both source and include
>files, functions and types.
>

I wish we could do that, but our shop isn't that formal.  In the previous
shop we did do that.

>I have been programming using these for almost 2 years and have never
>needed to add much more.


Oh yeah?  Well I've been using this header for 8 years.  :-)

-- 
Phil Mueller    mueller@b30news.b30.ingr.com
The preceeding opinions are not necessarily those of Intergraph Corporation.
Newsgroups: comp.software-eng