Style Manual

Miramar College
Computer and Information Sciences
for programming in "C" or "C++"

Prepared by: Ed Brunjes
Revision Date: 24 August 2005

I. Introduction

The guidelines contained in this document shall be followed during the creation of programs in partial fulfillment of course requirements of CISC 192 and CISC 241, and shall be considered minimum requirements for the preparation of each product. In the event these guidelines are modified, the most recent revision of the guidelines will take precedence. The instructor shall be informed in the event there are conflicts.

The intent of the guidelines is to provide consistency during software development. By following the guidelines, the product may be delivered in a standard format that can be easily understood by those reviewing the programming sequences.

II. Definition of Terms

II. General Package Guidelines

A. The development documentation may include but is not limited to IPO charts, class diagrams, hierarchy charts, flowcharts, and pseudocode. If pseudocode is present, it shall be in good form and shall maintain one inch margins at the top and bottom of each page, the left margin shall be one inch, and the right margin shall be no less than 1/2 inch. Each page shall be numbered and, if typed, shall be double spaced.

B. Source Code - The executable source code, including comments, shall be placed after the development documentation. Each page of code shall be separated at the perforation with all tractor-feed removed.

C. Output Samples - If required, the sample output of the program shall be placed after the Executable source code listing. The sample output shall demonstrate ALL aspects of the program. Each output sequence shall be separated from other sequences as appropriate and annotated where necessary. Each interactive input shall demonstrate operations on a substantial variety of data such as negative values, a positive values, and zero for numeric input. Additionally, all error trap, message, and prompt sequences must be demonstrated and annotated. All expected crash sequences shall be demonstrated and annotated.

If disk - oriented data files are created or accessed by the program, sample file contents shall be incorporated and annotated in the output portion of the package. A process for completing this on an MS-DOS operating system is presented below(for ASCII or text-type files).


type --> a:samp.dat > lpt1

IV. Source Code Style - Goal is readable, standardized code.


type fn_name(type data)

The style of the function declaration may be determined by the programmer. However the style of the declaration must be consistent throughout the programming sequence. Each user defined function must be prototyped in accordance with ANSI standards (1988). Refer to function declaration style samples below.


void fn_name(int x, int y) { statements; }

  • Naming Conventions

    a. Variables - should have noun-type names which relate to the data catagory or use of the data stored.

    b. Functions - should have active, verb-type names that relate to the activity of the function.

    c. Constants and Constant Variables - should have noun-type names which relate to the purpose or value referenced. The name shall be all capitol letters (and numbers).

    d. File Names - should be descriptive and relate to the purpose of the code contained in the file.

    e. Data File Names - should be descriptive and relate to the purpose of the data contained in the file. The extentions to the files should follow norman conventions (e.g. .TXT for text files, .DAT for text data files, and .BIN for binary data files).

    6. Restrictions -

    a. Recursion is not encouraged in beginning programming. Any recursive functions must be approved by the instructor prior to the implementation.

    b. The use of "goto" statements is NOT permitted.

    c. In general, functions should not exceed 100 executable statements in length.

    d. Use of global variables is NOT generally acceptable.

    e. Software modules should be "loosely coupled and highly cohesive". Inter-modual communication should occur by way of parameters and returned values.

    7. C++ Programming Standards

    V. Header Requirements - The following is designed to give specific guidance with respect to the header blocks.

    A. Function Header Format - Each function should begin with a comment header.

    
    

    /***********************************************************
    * Function Name: *
    * Date: *
    * Description of Output Parameters and *
    * Other Values Returned: *
    * Purpose of Function: *
    * Other functions called by this function: *
    * Programmer Name: *
    ***********************************************************/

    Figure 1. Function comment header format sample.

    1. Function Name.

    2. Date - The date which the function becomes operational. The date shall be in the format of a --

    
    

    December 30, 1999.

    3. Describe any parameters modified and returned and what if any value the function itself returns directly.

    4. Purpose of Function - Shall be descriptive of the overall intent of the function. The purpose shall include but not be limited to the function of the function in the overall program and how the function accomplishes its intent.

    5. Other functions called - A listing of the subroutines called by the function shall appear in the header.

    6. The name of the programmer.

    C. Program Header Format - The source file which contains the main programming unit shall have at its beginning a comment header.

    
    

    /************************************************************
    * Program Name: *
    * Date: *
    * Author(s): *
    * Modules (Files) Contained in the Program: *
    * Files Used by the Program: *
    * Purpose of the Program: *
    ************************************************************/

    Figure 2. Recommended Program header format.

    1. Program Name - The program name should be the same as the file name and shall conform to parameters given to DOS file names. Extensions should not be used as a part of the file name.

    2. Date - The date shall be the date the program becomes fully operational. The date shall be in the form of -- December 31, 1999.

    3. Author - Shall consist of the following information in approximately the displayed format --

    
    

    Author: author(s) name(s)

    Computer and Information Sciences Course No. ###

    Miramar College

    4. List of other source file modules that compose the program. These files will normally be compiled to .obj files that will be linked to form the final executable .exe program package.

    5. Files Used by the Program - Shall list all include files, data files, etc. that are used by the program.

    6. Purpose - a description of the overall intent of the program package. The purpose shall include, but not be limited to Program purpose, Program limitations, Design Concepts, Design Constraints, and Assumptions.

    D. Module Header Format - If the program consists of more than the one source file containing the one function main, the module header comment will be similar to the program header. Figure 3. displays a recommended format.

    
    

    /************************************************************
    * Module Name: *
    * Program Name: *
    * Date: *
    * Author(s): *
    * *
    * Files Used by this module: *
    * Functions included in this module: *
    * General Purpose of this module: *
    * *
    ************************************************************/

    Figure 3. Recommended Module header format.

    1. Module Name - The module name should be the same as the file name and shall conform to parameters given to DOS file names. Extensions should not be used as a part of the file name.

    2. Program Name - The name of the program that the module is part of.

    3. Date - The date shall be the date the program becomes fully operational. The date shall be in the form of -- December 31, 1999.

    4. Author - Shall consist of the following information in approximately the displayed format --

    Author: author(s) name(s)
    Computer and Information Sciences Course No. ###
    Miramar College

    5. Files Used by the Module - Shall list all include files, data files, etc. that are used by the module.

    6. Functions included in this module - lists all of the functions in this file.

    7. Purpose - Shall be a description of the part of the overall intent of the program the module performs. The purpose shall include, but not be limited to module purpose, Design Concepts, Design Constraints, and Assumptions.