CST 8110 - Algonquin College Header Format

The textbook writes function prototypes and headers in a form that is not acceptable for CST 8110 programming assignments.

You must learn to write your C code in the Algonquin College format.

Reference Guide

The Blue Book for CST 8110 by Arnold Betz contains the specification for Algonquin programming style. Function style, including headers and prototypes, is listed on pages 33 to 37.

Example

As an example, the course text writes a program and its functions in the following style:

#include <stdio.h>

int myfunction(int p1, int p2);   /* comment here */

int
main(void)
{
        int a;     /* comment here */
        int b;     /* comment here */
        int c;     /* comment here */

        a = 1;
        b = 2;

        c = myfunction(a, b);
        printf("%d\n", c);

        return(0);
}

int
myfunction(int one, int two)
{
        int temp;   /* comment here */

        temp = 10 * one + 30 * two;
        return(temp);
}

The style of the text is brief, which makes it suitable for textbook examples; but, it leaves out some important information. The Algonquin Standard for the same program is as follows:

/* HEADER ***********************************************************
 * . . . the Algonquin Program Header goes here . . .
 * END HEADER *******************************************************/

#include <stdio.h>

int
myfunction(/* RET: comment on the return value */
   int p1, /* IN: comment on first parameter */
   int p2  /* IN: comment on second parameter */
);

int
main(void)
{
   int a;     /* comment here */
   int b;     /* comment here */
   int c;     /* comment here */

   a = 1;
   b = 2;

   c = myfunction(a, b);
   printf("%d\n", c);

   return(0);
}

/* HEADER ***********************************************************
 * . . . the Algonquin Function Header goes here . . .
 * END HEADER *******************************************************/
int
myfunction(/* RET: comment on the return value */
   int p1, /* IN: comment on first parameter */
   int p2  /* IN: comment on second parameter */
)
{
   int temp;

   temp = 10 * p1 + 30 * p2;
   return(temp);
}

The points to note about the differences between the textbook style and Algonquin Style are:

• Every function has an Algonquin Function Header. (If the function is small, the header may well be bigger than the function itself.)
• Indent only three spaces, not more, not less.
• The arguments to the function are listed one per line, indented, with comments.
• Each argument to the function is documented by a comment on its own line, beginning with
  • "IN:", if the argument is being passed in to the function,
  • "OUT:", if the argument is being passed out of the function, or
  • "IN/OUT:" if the argument is being passed in, modified, and passed out again.
• The return value of the function is documented by a comment beginning "RET:".
• Note that the function prototype and the beginning of the function definition are identical. The prototype ends with a semicolon (';'), the definition has the function body following inside brace brackets ('{'...'}'). You can write one, then copy/paste it to create the other.