[ Last web update: August 13, 2012 ]

Department of Electrical & Computer Engineering
57:017 Computers in Engineering

Fall 2012

Software Design Protocol

This document has been developed as a guideline for all future homework submission, to help improve the quality of your programs and programming, where quality is measured in terms of:

1. More rapid design, implementation, and test cycles.
2. Improved software usage, reliability, and robustness.
3. Greater ease of readability and maintainability.

1. Required Programming Practices (including standards for source-included commenting/documenting).
2. Recommended Programming Practices, and
3. Forbidden Programming Practices.

Required Practices:
The following practices are considered inviolate. Petitions to waive these should be considered nearly futile.

1. All programs will conform to ANSI-supported standards for data types and function prototypes.
2. All variables must be explicitly declared.
3. Function names may be a mixture of upper and lower case letters and digits, and must begin with a lower case letter.
4. All variable naming should be consistent. A suggested style is to use a mixture of upper/lowercase letters but begin with an lower case (for example timeCounter), or use underscores "_" to separate words ( for example time_counter). Whatever you use, be consistent.
5. All #define constants and #define macro names must be entirely upper case letters and digits, and must begin with an upper case letter.
6. The constants TRUE and FALSE will be used where boolean values are implied. 0 and 1 are reserved to be used as integers only.
7. All file modules, and C functions should begin with a multi-line comment outlining the purpose, solution sketch, and input/output (parameters) of the object. See below for example.

Recommended Practices:
The following list of items are strongly recommended as conventions to improve readability and reliability. While not required, non-compliance may cost you some points.

1. All variables should be declared on the same source line as the type name.
2. Type names will be suffixed with _t and pointers will be suffixed with _p (or some other consistent naming convention).
3. Global variables are to be used only when it can be shown that locals and/or formal parameters cannot be used.
4. Global variable names should be unique across all related source files. Use a special naming convention for global variables, for example use the prefix "g_" as in g_pTimeCounter.
5. All functions should have a single return() point, and if possible, the return statement should be textually last in the function.
6. All input only parameters will carry the modifier const.
7. Use of single letter, "reusable" variables such as i, j, k, x, y, z should be minimized.
8. Use of on-the-fly type-casting should be minimized.
9. Use of the break and continue statements should be minimized.
10. Explicit braces should be used at all times to demonstrate control flow associations. For example:
    
    if(number == 1) {
    
    function1(alpha, number);
    
    }

Forbidden Practices:

1. No gotos or statement labels.
2. You may not modify the loop index variable of a for loop. FOR LOOPS are for counting loop situations in which the number of iterations the loop will execute is known upon entry to the first iteration of the loop. If this is not true for your loop, then you need a while loop instead.
3. Assignments may not be combined with conditional expressions. For example, if (x = y) is not a valid way to combine an assignment to x with a test of y for 0.

Pseudocode:

• Pseudocode is an artificial and informal language that helps you develop algorithms.
• Pseudocode is similar to everyday English; it is convenient and user friendly although it is not an actual computer programming language.
• Pseudocode programs are not executed on computers. Rather, they merely help you "think out" a program before attempting to write it in a programming language such as C.
• Pseudocode consists purely of characters, so you may conveniently type pseudocode programs into a computer using an editor program.
• Carefully prepared pseudocode programs may be converted easily to corresponding C programs.
• Pseudocode consists only of action statements-those that are executed when the program has been converted from pseudocode to C and is run in C. Definitions are not executable statements. They are messages to the compiler.
• Each variable should be listed and the purpose of each should be briefly mentioned at the beginning of the pseudocode program.

Guide for Pseudocode:

1. State your name
2. State the date
3. State the name of the subroutine.
4. Give a brief description of the function of the subroutine/program.
5. State the names of the input variables, their types, and give a brief description for each.
6. State the names of the output variables, their types, and give a brief description for each.
7. Give a list of instructions with enough detail that someone can translate the pseudocode into a computer language such as C, C++, Java, etc. Note, your pseudocode should paraphrase your algorithm and not look identical to C code.
8. Your pseudocode should be indented just like when you write your program. You should use {} or if/else/endif (for/endfor, while/endwhile, etc.) syntax to denote the start and end of blocks of statements.

Example Pseudocode:

Programmer: Gary E. Christensen
Date: 8/20/06
Name: print_matrix
Function: Print matrix nicely to screen.
Input: a[] = single subscripted int array of size arow * acol 
           = matrix to be printed.
       arow = int = number of rows of matrix a.
       acol = int = number of columns of matrix a.

       MAXSIZE = global constant that specifies the maximum size of the array
Output: matrix a[] printed to the screen.
Algorithm:

// Check for error conditions
if (arow <= 0) or (acol <= 0) then print error message and return endif
if (arow * acol > MAXSIZE) then print error message and return endif

// Print the matrix
k = 0
for i = 0 to arow - 1
   print bar '|'
   for j = 0 to acol - 1
      print a[k] right justified
      k = k + 1
   endfor
   print bar '|' followed by a newline
endfor

Documentation

Main Program and Subroutine Documentation

The main program and each subroutine must be documented with at least the following items.

Template for documentating main program and subroutines:

/******************************************************************
 *                                                                *
 * Programmer: <Your name goes here>                              *
 * Date: <Today's date>                                           *
 * Name: <function name goes here>                                *
 * Function: <Description of what the function does goes here>    *
 * Algorithm: <Describe how the function works>                   *
 * Input: <Name each input variable to the function on a separate *
 *     line and give a description of what it is and its type.>   *
 * Output: <Name each output variable on a separate line and      *
 *     give a description of what it is and its type.>             *
 *                                                                *
 ******************************************************************/

An example is the following

/*****************************************************************
 *                                                               *
 * Programmer: Gary Christensen                                  *
 * Date: 2/17/04                                                 *
 * Name: quicksort                                               *
 * Function: This function sorts an array of integers from       *
 *     smallest to largest value.                                *
 * Algorithm: This subroutine sorts a list of integers using     *
 *     recursion. The first element of the list is moved to      *
 *     its final position in the list and a sublist of numbers   *
 *     less than this number and a sublist of numbers greater    *
 *     than this number is created. Each sublist is then         *
 *     sorted by passing it to quicksort again. The              *
 *     termination condition for the recursion are as            *
 *     follows: A one element list is sorted by definition and   *
 *     is returned.                                              *
 * Input: ListOfInts - a pointer to an array of integers to be   *
 *     sorted.                                                   *
 *     size - the number of integers in the list to be sorted    *
 * Output: ListOfInts - a pointer to an array of sorted integers *
 *                                                               *
 *****************************************************************/

Structure Documetation

Each structure needs to be documented. The structure documentation must have the name, description, and description of each field of the structure. For example

/*****************************************************************
 *                                                               *
 * Programmer: Gary Christensen                                  *
 * Date: 3/25/2009                                               *
 * Name: complex                                                 *
 * Description: data type to hold a complex number               *
 * Fields:                                                       *
 *  real - float containing real part of comples number.         *
 *  imag - float containing imaginary part of complex number.    *
 *                                                               *
 *****************************************************************/
struct complex{
  float real;
  float imag;
};

/* struct complex is a data type to hold a complex number */
struct complex{
  float real;  /* real part of complex number */
  float imag;  /* imaginary part of complex number */
};

Object Documentation

Each object must have its own comment block that contains the object name and description. Each method and field of the object must be commented. Each trivial method of the object can have an inline comment, but any non-trivial method should have its own comment block as above. Each field of the object should have an inline comment that describes the field and its valid state. For example.