NetNews Usenet Archive 1992 #30/NN_1992_30.iso/spool/comp/software/4974

Text File | 1992-12-15 | 4.9 KB | 176 lines

Newsgroups: comp.software-eng
Path: sparky!uunet!infonode!ingr!b30news!mueller
From: [e-mail] ( Phil Mueller )
Subject: Re: C Code Layout [long]
Message-ID: <[e-mail]>
Sender: [e-mail] (Phil Mueller)
Organization: Intergraph
References: <[e-mail]> <[e-mail]>
Date: Tue, 15 Dec 1992 13:06:15 GMT
Lines: 164

In article <[e-mail]> [e-mail] writes:
>In article [e-mail], [e-mail] ( 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    [e-mail]
The preceeding opinions are not necessarily those of Intergraph Corporation.