home *** CD-ROM | disk | FTP | other *** search
/ NetNews Usenet Archive 1992 #30 / NN_1992_30.iso / spool / comp / software / 4886 < prev    next >
Encoding:
Text File  |  1992-12-11  |  2.4 KB  |  70 lines
  1. Path: sparky!uunet!cs.utexas.edu!zaphod.mps.ohio-state.edu!darwin.sura.net!udel!princeton!siemens!kong!wood
  2. From: wood@siemens.com. (Jim Wood)
  3. Newsgroups: comp.software-eng
  4. Subject: Re: C Code Layout
  5. Message-ID: <wood.724079768@kong>
  6. Date: 11 Dec 92 13:16:08 GMT
  7. References: <AJ3U.92Dec6151332@larch.cs.virginia.edu> <1992Dec7.113438.13054@spider.co.uk> <1g3to7INNd11@uwm.edu> <1992Dec11.080937@eklektix.com>
  8. Sender: news@siemens.siemens.com
  9. Lines: 59
  10.  
  11. My format for C code modules:
  12.  
  13. /* - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
  14.    Module:  X.C
  15.    Purpose: ....
  16.    Author:  Jim Wood, Siemens Corporate Research, Inc. (609) 734-3643
  17.    Group:   Software Testing
  18.    Project: SSP (Sample Stupid Project)
  19.    - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
  20.    Functions defined in this module:
  21.     Add:            Integer X Integer --> Integer
  22.     Is_Positive:        Integer --> Boolean
  23.    Macros defined in this module:
  24.     MINIMUM:        Integer X Integer --> Integer
  25.     MAXIMUM:        Integer X Integer --> Integer
  26.    Data types defined in this module:
  27.     complex_number:        {Integer, Integer}
  28.    Global variables declared in this module:
  29.     Generate_Identifier:    unique identifier increment
  30.    - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - */
  31.  
  32. #include "type.h"        /* data type definitions */
  33. #include "universe.h"        /* macros and constants for all modules */
  34. #include "a.h"            /* modules related to this one */
  35. #include "b.h"
  36. #include "c.h"
  37.  
  38.  
  39. INTEGER Add(a, b)
  40.   INTEGER    a,        /* first integer to add */
  41.         b;        /* second integer to add */
  42. /*
  43.   PRE  A precondition goes here.
  44.   POST The sum of two integers is returned.
  45.   GENL General comments go here.
  46.   NOTE Special notes, especially for maintenance, go here.
  47. */
  48. {
  49.   INTEGER    index = 0;    /* local integer variable */
  50.  
  51.   return(a + b);
  52. } /* end ADD */
  53.  
  54. ....
  55.  
  56. The point is to define standard header comments for the module, write
  57. comments for each routine in the module, write short descriptive comments
  58. for each formal parameter and local variable of each routine, and also to
  59. identify the end of a routine.
  60.  
  61. Clarity and brevity are the main keywords.  If people are to understand
  62. the code, the need to quickly know what each routine does and what each
  63. variable means.
  64.  
  65. --
  66. Jim Wood [jwood@siemens.siemens.com] (609) 734-3643
  67. "Rise up on the wings of eagles, and two step among the stars.
  68.  You are not forgotten.  Your smile will echo forever."
  69.    -- Ryerson Schwark, to our friend Rob Bernardo.
  70.