From: morrison@eng.auburn.edu (Kelly Morrison)
Subject: Still more C coding style comments...
Reply-To: morrison@eng.auburn.edu
Organization: Auburn University Engineering
Date: Tue, 15 Dec 1992 05:56:48 GMT


After writing several very large X Window System programs, I decided that I
needed a better way to write and comment C programs. Here's what I did:

1. I took the "xedit" text editor provided with the X Window System
   distribution and modified it to read in an optional text file containing
   templates. The editor then creates new pull-down menus which will insert
   the templates into the text when requested.

   Here's an example. Let's say you want to have templates available for
   including the standard C headers, functions, and main programs. You could
   create the following file:

   MENU C utilities
   
   LABEL standard headers
   &
   #include <stdio.h>
   #include <string.h>
   &

   LABEL function
   &
   static void func()
   {
   }
   &

   LABEL main program
   &
   main (argc, argv)
   int   argc;
   char  *argv[];
   {
   }
   &

   ENDMENU

   When you invoke the xedit editor, it parses this file and creates a new
   menu button labeled "C utilities". The menu attached to this button has
   three items attached to it: "standard headers", "function", and "main
   program". If you select one of these items, the text found between the
   & delimiters is pasted into the document. For example, clicking on the
   "standard headers" menu item will cause the two #include lines to be
   pasted in the document. You can describe as many menus as you would like,
   and you can also separate menu items using a dashed line.

   This lets you write templates for all of the program components you
   normally use so that they are available at the click of a mouse. I
   keep a fairly large template file that has most of the commonly used
   C, X11R4, and Athena calls, along with a menu of comment templates.
   I also have a different menu file that I use for electronic grading.

2. Using this modified editor, I started creating comment standards for my
   programs. I have to distribute software to lab students each quarter, so
   it helps if they can read it with a high degree of understanding. (Some
   feel that my code is adequately commented; some feel it is OVERcommented.)
   Random examples follow, from both C and Pascal programs:


Here's what my program headers look like:

(*******************************************************************************
*               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                              *
*                                                                              *
* This is a compiler for a small subset of Pascal described in:                *
*
*    SYSTEM SOFTWARE: An Introduction to Systems Programming, Second Edition   *
*       by Leland L. Beck, San Diego State University.                         *
*       Addison-Wesley Publishing Company, Reading, Massachusetts, 1990.       *
*                                                                              *
* This compiler uses a recursive descent parsing technique to translate        *
* programs written in this Pascal subset into a stream of SIC (Simplified      *
* Instructional Computer) assembly code. SIC is a hypothetical computer also   *
* described in Beck that was designed for educational purposes.                *
*                                                                              *
* The code for this compiler is distributed among a number of modules. The     *
* following are the files which make up the Babe compiler:                     *
*                                                                              *
* 1. main.p       : The driver program for the compiler. This program opens    *
*                   a Babe source program and creates an output file for the   *
*                   SIC program. It also contains the procedures corresponding *
*                   to each of the productions in the Babe grammar.            *
      <<<etc., etc., etc.>>>
* 9. Makefile     : The makefile for the Babe compiler. To make an executable  *
*                   version of the compiler, just type:                        *
*                      make babe                                               *
*                                                                              *
*    Programmer : Kelly Morrison, Auburn University                            *
*    Date       : February 29, 1992                                            ********************************************************************************)



Each major chunk of the program has a banner so I can find it in a hurry. For
example:

/*******************************************************************************
*                  V A R I A B L E   d e c l a r a t i o n s
*******************************************************************************/
static FILE *InFile,    /* The input file containing SIC macro instructions */
            *OutFile;   /* The output file of expanded macro instructions */
 
/* Input and output file names. */
static char *InputFileName;
static char *OutputFileName;
 
/* Error message to display when the program is invoked incorrectly. */
static char *UsageError[] = {
   "Usage: macro [-c] [-d] [-e] filename                              ",
   "       -c : Comments in the macro definitions should be retained  ",
   "            in the macro expansions. Default is to omit them.     ",
   "       -d : The original macro definition will be included as a   ",
   "            series of comments. Default is to omit the definition.",
   "       -e : Echo the expanded file to the screen.                 ",
   0
};



Comments for all functions have the following format:
/*******************************************************************************
*                              DEF_Insert_Line()
* Purpose:
*    Inserts a LINE of text into the definitions table.
* Parameters:
*    TheLine : The LINE of text to be inserted into the table.
* Returns:
*    The position of the line in the definitions table if the line was
*    installed successfully; or DEF_OVERFLOW if the table was already full and
*    the line could not be inserted.
* Global variables used:
*    DEFTAB : The DEFinitions TABle.
*    CurrentKey : The Key of the last line installed in the table.
*    DEF_MAX_TABLE_SIZE : The maximum number of LINEs which the definitions
*       table can store. This is a #define which is found in "support.h".
*    DEF_OVERFLOW : An error code which indicates that there was no room in the
*       definitions table to insert the line. This is a #define which is found
*       in "support.h".
*******************************************************************************/
KEY DEF_Insert_Line(The_Line)
   LINE The_Line;
{
#ifdef DEBUG
   printf ("<DEF_Insert_Line> The_Line=<%s>\n", The_Line);
#endif
 
   /* See if the table exists. */
   if (!DEFTAB)
      {
      fprintf (stderr, "Error using the DEF routines!\n");
      fprintf (stderr, "   You must call DEF_Initialize() to initialize\n");
      fprintf (stderr, "   the definitions table before trying to call the\n");
      fprintf (stderr, "   DEF_Insert_Line() function!\n");
      exit(0);
      }
 
   /* See if there is room left in the table to store a line. */
   if (++CurrentKey >= DEF_MAX_TABLE_SIZE)
      {
      --CurrentKey;
      return (DEF_OVERFLOW);
      }
 
   /* Try to allocate room for the line. */
   DEFTAB[CurrentKey] = (LINE) calloc(1, strlen(The_Line)+1);
 
   /* See if the memory allocation succeeded. */
   if (!DEFTAB[CurrentKey])
      {
      --CurrentKey;
      return (DEF_OVERFLOW);
      }
 
   /* Copy the line into the definitions table. */
   strcpy (DEFTAB[CurrentKey], The_Line);
 
   /* Return the key corresponding to this line. */
   return(CurrentKey);
}
 


Anyway, that's how I code. I've written a compiler, an assembler, a reverse engineering
tool for Ada that extracts Booch-like diagrams (written in C using X11R4, some custom-
made widgets, and PostScript output), and the bulk of the interface code for a NASA
project here at Auburn using documentation like this.

I'm always open to suggestions!!! Please (ahem) COMMENT on my style... :)