ECE Undergraduate Linux Laboratory Documentation Standards

1. Program Headers

The following is a good model of a program header:

////////////////////////////////////////////////////////
// ECE 272 Lab                                        //
// NAME:        Firstname Lastname                    //
// SECTION:     Four (12:20 - 2:20) M                 //
// DATE DUE:    Feb. 1, 1998                          //
// FILENAME:    somefile.extension                    //
// PROJECT:     Lab Assignment #1                     //
// PURPOSE:     This assembly program calculates the  //
//              ASCII sum of the characters passed to //
//              it as a character array.              //
////////////////////////////////////////////////////////

A brief explanation of some of the entries:

filename: This should simply contain the name of the file in which this header is residing.
project: Should contain the name of the overall project.
purpose: Should briefly explain the what this program does.

Program headers are included once per assignment at the top of the document.

2. Procedure Headers

The following is a good model of a procedure header:

/////////////////////////////////////////////////////
// PROCEDURE:   ProcedureName                      //
// PARAMETERS:  Listing of parameters              //
// RETURNS:     Listing of data that gets returned //
// DESCRIPTION: What this procedure does           //
/////////////////////////////////////////////////////

A brief explanation of some of the entries:

procedure: Actual call name of the procedure. Use mixed case to emphasize procedure names like GetString instead of get_string.
parameters: Describe the registers or data passed into this procedure from the calling procedure.
returns: List any data being sent to the calling procedure upon termination of this procedure.
description: This should explain in detail the function of this procedure. Don't explain exactly how the procedure performs what you claim it can do, just explain what it does. How should be expressed in the procedure in comments.

If a C program has only main, then there is no need for a procedure header. This is the only case when this is allowed simply because main is self explanatory.

3. Variables

Our use of assembly language will involve variables. By assigning them meaningful names in a defined format, reading and debugging these procedures will become easier. We will set up our programs to be case sensitive, whenever possible.

constants: Constants should be all capitalized, such as NULL, PI, or CR.
procedure names: Procedure names should use mixed case whenever possible, such as GetString, Sum, or ComputeAvg.
local variables: Local variables should be all lower case, such as sum, count, total, or value.
globals: Globals should be proceeded by a _, such as _TRYTYPE, _BUFFER, or _STARTVALUE.

4. Sample

We'll now run through a simple example of the code for the first assignment, Lab #1. The code is provided to you but does not have the appropriate documentation standards expressed here. Note that the code expressed here does NOT include line-by-line comments, which it should. This is obviously because that is left up to you to figure out.

First, the C file :

////////////////////////////////////////////////////////
// ECE 272 Lab                                        //
// NAME:        Joe Smith                             //
// SECTION:     Four (12:20 - 2:20) M                 //
// DATE DUE:    Feb. 1, 1998                          //
// FILENAME:    drv.c                                 //
// PROJECT:     Lab Assignment #1                     //
// PURPOSE:     This C program prompts the user for   //
//              a string terminated with a newline    //
//              character.  It then makes a call to   //
//              an assembly function named asum and   //
//              prints the ASCII sum returned by that //
//              function.                             //
////////////////////////////////////////////////////////

main() {
  char buffer[256];
  do {
    int i = 0;
    printf("Enter a string terminated with a newline\n");
    do {
      buffer[i] = getchar();
    } while(buffer[i++] != '\n');
    buffer[i-1] = 0;
    i = asum(buffer);
    if(i) {
      printf("ascii sum is %d\n", i);
      continue;
    }
  } while(1);
}

And now the Assembly file :

////////////////////////////////////////////////////////
// ECE 272 Lab                                        //
// NAME:        Joe Smith                             //
// SECTION:     Four (12:20 - 2:20) M                 //
// DATE DUE:    Feb. 1, 1998                          //
// FILENAME:    asm.s                                 //
// PROJECT:     Lab Assignment #1                     //
// PURPOSE:     This Assembly program calculates the  //
//              ASCII sum of an array of characters   //
//              passed to it.                         //
////////////////////////////////////////////////////////
	.file "asm.s"
        .align 16
        .global asum
        .type asum,@function

/////////////////////////////////////////////////////
// PROCEDURE:   asum                               //
// PARAMETERS:  A character array placed on the    //
//              stack.                             //
// RETURNS:     The ASCII sum of the characters of //
//              the array.                         //
// DESCRIPTION: Sums up the ASCII values of an     //
//              array of characters.               //
/////////////////////////////////////////////////////
asum:
        pushl %ebp # 34qfwasfd
        movl  %esp,  %ebp
        subl  $4, %esp
        movl  $0, -4(%ebp)
.L2:
        movl   8(%ebp), %eax
        cmpb   $0, (%eax)
        jne    .L4
        jmp    .L3
        .align 16
.L4: 
        movl   8(%ebp), %eax
        movsbl (%eax), %edx
        addl   %edx, -4(%ebp)
        incl   8(%ebp)
        movl    $-1, %ebx
        jmp    .L2
        .align 16
.L3:
        movl   -4(%ebp), %eax
        jmp    .L1
        .align 16
.L1:
        movl   %ebp, %esp
        popl   %ebp
        ret
.Lfel:
        .size  asum, .Lfel-asum

ECE Undergraduate Linux Laboratory Documentation Standards