home *** CD-ROM | disk | FTP | other *** search
/ NetNews Usenet Archive 1992 #30 / NN_1992_30.iso / spool / comp / software / 4965 < prev    next >
Encoding:
Text File  |  1992-12-15  |  8.5 KB  |  202 lines
  1. Newsgroups: comp.software-eng
  2. Path: sparky!uunet!haven.umd.edu!darwin.sura.net!news.duc.auburn.edu!gauss.cse!morrison
  3. From: morrison@eng.auburn.edu (Kelly Morrison)
  4. Subject: Still more C coding style comments...
  5. Message-ID: <1992Dec15.055648.28130@news.duc.auburn.edu>
  6. Sender: usenet@news.duc.auburn.edu (News Account)
  7. Nntp-Posting-Host: gauss.cse.eng.auburn.edu
  8. Reply-To: morrison@eng.auburn.edu
  9. Organization: Auburn University Engineering
  10. Date: Tue, 15 Dec 1992 05:56:48 GMT
  11. Lines: 189
  12.  
  13.  
  14. After writing several very large X Window System programs, I decided that I
  15. needed a better way to write and comment C programs. Here's what I did:
  16.  
  17. 1. I took the "xedit" text editor provided with the X Window System
  18.    distribution and modified it to read in an optional text file containing
  19.    templates. The editor then creates new pull-down menus which will insert
  20.    the templates into the text when requested.
  21.  
  22.    Here's an example. Let's say you want to have templates available for
  23.    including the standard C headers, functions, and main programs. You could
  24.    create the following file:
  25.  
  26.    MENU C utilities
  27.    
  28.    LABEL standard headers
  29.    &
  30.    #include <stdio.h>
  31.    #include <string.h>
  32.    &
  33.  
  34.    LABEL function
  35.    &
  36.    static void func()
  37.    {
  38.    }
  39.    &
  40.  
  41.    LABEL main program
  42.    &
  43.    main (argc, argv)
  44.    int   argc;
  45.    char  *argv[];
  46.    {
  47.    }
  48.    &
  49.  
  50.    ENDMENU
  51.  
  52.    When you invoke the xedit editor, it parses this file and creates a new
  53.    menu button labeled "C utilities". The menu attached to this button has
  54.    three items attached to it: "standard headers", "function", and "main
  55.    program". If you select one of these items, the text found between the
  56.    & delimiters is pasted into the document. For example, clicking on the
  57.    "standard headers" menu item will cause the two #include lines to be
  58.    pasted in the document. You can describe as many menus as you would like,
  59.    and you can also separate menu items using a dashed line.
  60.  
  61.    This lets you write templates for all of the program components you
  62.    normally use so that they are available at the click of a mouse. I
  63.    keep a fairly large template file that has most of the commonly used
  64.    C, X11R4, and Athena calls, along with a menu of comment templates.
  65.    I also have a different menu file that I use for electronic grading.
  66.  
  67. 2. Using this modified editor, I started creating comment standards for my
  68.    programs. I have to distribute software to lab students each quarter, so
  69.    it helps if they can read it with a high degree of understanding. (Some
  70.    feel that my code is adequately commented; some feel it is OVERcommented.)
  71.    Random examples follow, from both C and Pascal programs:
  72.  
  73.  
  74. Here's what my program headers look like:
  75.  
  76. (*******************************************************************************
  77. *               B A B E  C o m p i l e r   V e r s i o n   1 . 1               *                          *                       written by Kelly Morrison                              *
  78. *                                                                              *
  79. * This is a compiler for a small subset of Pascal described in:                *
  80. *
  81. *    SYSTEM SOFTWARE: An Introduction to Systems Programming, Second Edition   *
  82. *       by Leland L. Beck, San Diego State University.                         *
  83. *       Addison-Wesley Publishing Company, Reading, Massachusetts, 1990.       *
  84. *                                                                              *
  85. * This compiler uses a recursive descent parsing technique to translate        *
  86. * programs written in this Pascal subset into a stream of SIC (Simplified      *
  87. * Instructional Computer) assembly code. SIC is a hypothetical computer also   *
  88. * described in Beck that was designed for educational purposes.                *
  89. *                                                                              *
  90. * The code for this compiler is distributed among a number of modules. The     *
  91. * following are the files which make up the Babe compiler:                     *
  92. *                                                                              *
  93. * 1. main.p       : The driver program for the compiler. This program opens    *
  94. *                   a Babe source program and creates an output file for the   *
  95. *                   SIC program. It also contains the procedures corresponding *
  96. *                   to each of the productions in the Babe grammar.            *
  97.       <<<etc., etc., etc.>>>
  98. * 9. Makefile     : The makefile for the Babe compiler. To make an executable  *
  99. *                   version of the compiler, just type:                        *
  100. *                      make babe                                               *
  101. *                                                                              *
  102. *    Programmer : Kelly Morrison, Auburn University                            *
  103. *    Date       : February 29, 1992                                            ********************************************************************************)
  104.  
  105.  
  106.  
  107. Each major chunk of the program has a banner so I can find it in a hurry. For
  108. example:
  109.  
  110. /*******************************************************************************
  111. *                  V A R I A B L E   d e c l a r a t i o n s
  112. *******************************************************************************/
  113. static FILE *InFile,    /* The input file containing SIC macro instructions */
  114.             *OutFile;   /* The output file of expanded macro instructions */
  115.  
  116. /* Input and output file names. */
  117. static char *InputFileName;
  118. static char *OutputFileName;
  119.  
  120. /* Error message to display when the program is invoked incorrectly. */
  121. static char *UsageError[] = {
  122.    "Usage: macro [-c] [-d] [-e] filename                              ",
  123.    "       -c : Comments in the macro definitions should be retained  ",
  124.    "            in the macro expansions. Default is to omit them.     ",
  125.    "       -d : The original macro definition will be included as a   ",
  126.    "            series of comments. Default is to omit the definition.",
  127.    "       -e : Echo the expanded file to the screen.                 ",
  128.    0
  129. };
  130.  
  131.  
  132.  
  133. Comments for all functions have the following format:
  134. /*******************************************************************************
  135. *                              DEF_Insert_Line()
  136. * Purpose:
  137. *    Inserts a LINE of text into the definitions table.
  138. * Parameters:
  139. *    TheLine : The LINE of text to be inserted into the table.
  140. * Returns:
  141. *    The position of the line in the definitions table if the line was
  142. *    installed successfully; or DEF_OVERFLOW if the table was already full and
  143. *    the line could not be inserted.
  144. * Global variables used:
  145. *    DEFTAB : The DEFinitions TABle.
  146. *    CurrentKey : The Key of the last line installed in the table.
  147. *    DEF_MAX_TABLE_SIZE : The maximum number of LINEs which the definitions
  148. *       table can store. This is a #define which is found in "support.h".
  149. *    DEF_OVERFLOW : An error code which indicates that there was no room in the
  150. *       definitions table to insert the line. This is a #define which is found
  151. *       in "support.h".
  152. *******************************************************************************/
  153. KEY DEF_Insert_Line(The_Line)
  154.    LINE The_Line;
  155. {
  156. #ifdef DEBUG
  157.    printf ("<DEF_Insert_Line> The_Line=<%s>\n", The_Line);
  158. #endif
  159.  
  160.    /* See if the table exists. */
  161.    if (!DEFTAB)
  162.       {
  163.       fprintf (stderr, "Error using the DEF routines!\n");
  164.       fprintf (stderr, "   You must call DEF_Initialize() to initialize\n");
  165.       fprintf (stderr, "   the definitions table before trying to call the\n");
  166.       fprintf (stderr, "   DEF_Insert_Line() function!\n");
  167.       exit(0);
  168.       }
  169.  
  170.    /* See if there is room left in the table to store a line. */
  171.    if (++CurrentKey >= DEF_MAX_TABLE_SIZE)
  172.       {
  173.       --CurrentKey;
  174.       return (DEF_OVERFLOW);
  175.       }
  176.  
  177.    /* Try to allocate room for the line. */
  178.    DEFTAB[CurrentKey] = (LINE) calloc(1, strlen(The_Line)+1);
  179.  
  180.    /* See if the memory allocation succeeded. */
  181.    if (!DEFTAB[CurrentKey])
  182.       {
  183.       --CurrentKey;
  184.       return (DEF_OVERFLOW);
  185.       }
  186.  
  187.    /* Copy the line into the definitions table. */
  188.    strcpy (DEFTAB[CurrentKey], The_Line);
  189.  
  190.    /* Return the key corresponding to this line. */
  191.    return(CurrentKey);
  192. }
  193.  
  194.  
  195.  
  196. Anyway, that's how I code. I've written a compiler, an assembler, a reverse engineering
  197. tool for Ada that extracts Booch-like diagrams (written in C using X11R4, some custom-
  198. made widgets, and PostScript output), and the bulk of the interface code for a NASA
  199. project here at Auburn using documentation like this.
  200.  
  201. I'm always open to suggestions!!! Please (ahem) COMMENT on my style... :)
  202.