Make your own free website on Tripod.com

Introduction

 

Standards for writing software are often regarded with distaste.  However, in almost every organization, standards are a fact of life.  Standards will be required and enforced for all programs written for any programming course taken at Webster University.   These may not be the same exact standards required by any particular company, but these standards will prepare you for programming with any set of standards.  In order to receive the maximum grade possible on programming assignments, the student must adhere to these standards.

 

Naming Conventions

 

General Rule –  Data Variable Names

 

In general, all data variable names should begin with a lower case letter.  The remaining letters in each word should be lower case. Variable names should be meaningful and descriptive of the data that they represent.

 

Nonstandard:

 

e

stuff

SUMOFGRADES

 

Department Standard:

 

employee

sum_of_grades

sumOfGrades

 
 

 

 

 

 

 

 

Department Standard:

 

current_customer

previous_customer

 

 

Nonstandard:

 

customer1

customer2

 

 
 

 

 

 

 


General Rule – Object Variable Names

 

In general, all object variable names should begin with an upper case letter.  The remaining letters in each word should be lower case. Variable names should be meaningful and descriptive of the data that they represent.

Department Standard:

 

Employee

Customer

Grades

 

Nonstandard:

 

E

customer

Stuff

 
 

 

 

 

 

 

 


Function Names

 

Function names should generally be a verb phrase (e.g. verb followed by noun).  It is acceptable to abbreviate certain common words provided that the abbreviation is well known.

Department Standard:

 

GetMemory (  )

Init_Employee_Struct ( )

CheckMsgTable ( )

Check_Message_Table ( )

 

Nonstandard:

 

Memory (  )

Initemployeestruct (  )

CkMsgT (  )

Function1 (  )

 
 

 

 

 

 

 

 

 

 

 


Data Member Names (Classes and Structures)

 

When naming member data variables, follow the data variable names rules.   Member names (except for the constructor and destructor) should never be the same as the struct or class that defines them.

Department Standard:

 

Airplane.name

Employee.firstName

 

Nonstandard:

 

Airplane.airplane

Employee.fn

 

 
 

 

 

 

 

 

 

 

 

 


Public Member Function Names  (Classes and Structures)

 

 When naming public member functions, follow the rules for function names. 

Department Standard:

 

Airplane. SetFuelLevel ( )

Employee.Get_Ssn ( )

 

Nonstandard:

 

Airplane.Fuel ( )

Employee.Gssn ( )

 

 
 

 

 

 

 

 

 

 


 


Private Member Function Names  (Classes and Structures)

 

Private member functions should begin with an underscore, and otherwise follow the rules for function names. 

Department Standard:

 

Airplane._SetFuelLevel ( )

Employee._Calculate_Pay ( )

 

Nonstandard:

 

Airplane.SetFuelLevel ( )

Employee.Calculate_Pay ( )

 

 
 

 

 

 

 

 

 

 

 

 


Pointer Names

 

Pointer names should begin with a lower case ‘p’ followed by the variable name of the data at which they point. 

Department Standard:

 

pStudentNumber

Employee.pNumber

 

Nonstandard:

 

StudentNumberPtr

Employee.PNumber

pEmployee.Number

 
 

 

 

 

 

 

 

 

 

 


Constant Names

 

Use const to define constant values.  Constants should be uppercase.

Department Standard:

 

const int  MAX_CREDITS = 18;

const float CM_PER_IN = 2.54;

 

 

Nonstandard:

 

#define MAX_CREDITS 18

#define CM_PER_IN  2.54

 

 
 

 

 

 

 

 

 



Indentation

 

General Rule

 

The size of an indent level is 4 columns.   If the tab level is set to 4 spaces, then either the space bar or the tab key may be used.  The tab character can cause portability problems unless the text editor changes the tab to 4 spaces.

 

 

Indentation of Control Structures

 

The opening and closing braces of a control structure (e.g. a for statement or an if-else statement) should always be on an otherwise blank line.  The curly braces should appear in the  same column as the start column of their corresponding control structure.  Related (open and close pair) curly braces should always be aligned in the same column. 

Department Standard:

 

if (  count == 10 )

{

    DisplayTotal ( );

}

 

Nonstandard:

 

if (  count == 10 )

    {

    DisplayTotal ( );

    }

 

 
 

 

 

 

 

 

 

 

 

Department Standard:

 

do

{

    Get_Next_Grade ( );

}

while ( grade ! =  -99 );

 

Nonstandard:

 

do

{

    Get_Next_Grade ( );

}while ( grade ! =  -99 );

 

 
 

 

 

 

 

 

 

 

 

Department Standard:

 

for ( x = 0; x < 10 ; x++ )

{

    Get_Student_Id (  );

    Get_Student_Name (  );

}

 

Nonstandard:

 

for ( x = 0; x < 10 ; x++ ){

    Get_Student_Id (  );

    Get_Student_Name (  );}

 

 
 

 

 

 

 

 

 

 



Indentation of If and Else

 

The if statement is coded on a line by itself.  Likewise, the else statement is ordinarily coded on a line by itself.  However, if the else is followed by an if which is the only if statement subordinate to that else, the if and its conditional expression may go on the same line as the else and no additional nesting or indentation is required.

Department Standard:

 

if (  count == 10 )

{

    cout << “\n”;

}

else if ( count > 10  )

{

    cout << “\t”;

    count = 1;

}

 

Nonstandard:

 

 

if (  count == 10 )

{

    cout << “\n”;

}

else

{

        if (count > 10 )

        {

            cout << “\t”;

            count = 1;

         }

}

 

 
 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 


If a conditional expression is made up of multiple subexpressions, each subexpression should be surrounded in its own set of parentheses. 

 

 

Department Standard:

 

if ( (count == 10 ) && (total < 99) )

{

    cout << “\n”;

}

 

 

Nonstandard:

 

if ( count == 10  && total < 99 )

{

    cout << “\n”;

}

 

 
 

 

 

 


.

 

 

 

 

 


 

 

If a conditional expression is made up of  multiple subexpressions, and each subexpression is lengthy, then each subexpression should be coded on a separate line.

 

Department Standard:

 

if ( (count_Before_Adjustment  == 10 ) &&

     (total_Before_Adjustment  < 99) ) &&

     (total_After_Adjustment  < 99) )

{

    cout << “\n”;

}

 

 
 

 

 

 


.

 

.

 

 

 

Nonstandard:

 

if ( (count_Before_Adjustment  == 10 ) && (total_Before_Adjustment  < 99) ) ) && (total_After_Adjustment  < 99) )

{

    cout << “\n”;

}

 

 
 

 

 

 

 

 

 

 

 

 

 

 


Line length and Indentation of Continued Lines

 

Maximum line length of a source code line shall be 78 characters, including all blank characters.  Cleanly split longer lines to improve readability.  The continued line should be indented.

Department Standard:

 

cout     <<  setw ( 25 )   <<  Employee.first_Name

            <<   setw ( 10 )  <<  Employee.last _Name

            <<   setw ( 35 )  <<  Employee.home_Address;

           

 
 

 

 

 

 

 

 

Nonstandard:

 

cout     <<  setw ( 25 )  <<  Employee.First_Name  <<   setw ( 10 )  <<  Employee.last _Name  <<   setw ( 35 )  <<  Employee.home_Address

 

 
 

 

 

 

 



Indentation of Inline Comments

 

Inline comments associated declarations should be aligned with one another, in a column which is  also associated with a tab stop.

Department Standard:

 

int        student_id,                             //   student SSN or number or id

            credits;                                   //   number of credits of enrollment

 

 
 

 

 

 

 

 

 

 

Nonstandard:

 

 

int        student_id,                             //   student SSN or number or id

            credits;                       //   number of credits of enrollment

 

 

 
 

 

 

 

 

 

 

 

 

 


Control Structures

 

 

Control Structures with only one statement

 

When the control structure (e.g., while, if, for) has only one statement in its body, it should still be coded so that the single statement is enclosed in curly braces (even though the braces are not required in C++).   

 

Department Standard:

 

if (  count == 10 )

{

    DisplayTotal ( );

}

 

Nonstandard:

 

if (  count == 10 )

    DisplayTotal ( );

 

 

 

Nonstandard:

 

if (  count == 10 )   DisplayTotal ( );

 

 

 
 

 

 

 

 

 

 

 

 

 

 

 

 


GOTO and BREAK

 

The use of goto and break to terminate loop structure is not permitted.  The use of ‘break’ is restricted to ‘switch’ statements. Goto is never permitted.   Every block of code should have one entry and one exit point;

 

 

 

 

Return ( )

 

Every function should have exactly one entry point and one exit point.  It is never permissible to use more than one return statement in a function.

 

Department Standard:

 

int total = 0;

 

if (  count == 10 )

{

    total = 7;

}

else

{

    total  = 3;

}

return total;

 

Nonstandard:

 

if (  count == 10 )

{

    return ( 7 );

}

else

{

    return ( 3 );

}

 

 
 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 


 

 


Other Style Requirements

 

 

One Statement Per Line

 

Each coding line should contain only one statement.

Department Standard:

 

total = 0;

average = 0.0;

 

Nonstandard:

 

total = 0;  average = 0.0;

 

 
 

 

 

 

 

 

 

 

 


Pointer and Reference Parameter Declaration

 

Pointers should be declared with the . * part of the type.

Reference variables should also associate the & with the type;

 

Department Standard:

 

int*       pStudent;

int*       pNumber;

 

 

Nonstandard:

 

int        *pStudent,

            *pNumber;

 

 

 

Department Standard:

 

void swap (int&  num1,

                   int&  num2)

 

 

Nonstandard:

 

void swap (int  &num1,

                   int  &num2)

 

 

 
 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 


 


Variable Declaration Style

 

Each variable must be declared on a separate line. Group variables of the same data type together and indent to the same level.

Department Standard:

 

int   number_students,

       test_number;

float     student_average,

            class_average;

 

Nonstandard:

 

int   number_students,  test_number;

float     student_average,  class_average;

 

 
 

 

 

 

 

 

 

 

Nonstandard:

 

int   number_students;

int   test_number;

float     student_average;

float     class_average;

 
 

 

 

 

 

 

 

 

 

 

 

 


Other Standards Requirements

 

 

Use C++ not C Statements

 

 

C++ is not C.   Do not write C code, compile it with a C++ compiler, and try to pretend that it's C++.

 

Department Standard:

 

cout << Total;

 

 

 

Nonstandard:

 

printf (“%d”,Total );

 

 

 
 

 

 

 

 


Department Standard:

 

// comments

 

Nonstandard:

 

/* comments */

 
 

 

 

 

 

 

 

Use Reference Parameters

 

Avoid using pointers when reference parameters can accomplish the same goal. Pointers to pointers should always be avoided. Unlike a pointer, a reference cannot be changed to point to another object or variable.

 

Department Standard:

 

void swap (int&  num1,

                  int&  num2)

 

 

Nonstandard:

 

void swap (int *  num1,

                  int*   num2)

 

 

 
 

 

 

 

 

 

 

 

 

 


Use if-else not ?:

 

Avoid using the ?  :  operators.  Even though it is fewer keystrokes, it diminishes readability of the program.  The days of terse cryptic code are over.  Make it readable. Always make the code obvious.

 

Nonstandard:

 

total =  count == 10 ?7:3;

 

 

 

Department Standard:

 

if (  count == 10 )

{

    total = 7;

}

else

{

    total  = 3;

}

 

 
 

 

 

 

 


 

 

 

 

 

 

 

 

 

 


 

 

Eliminate All Compiler Warnings

 

 

Eliminate all compiler warnings.  The most common warnings that students encounter are “unreferenced local variable”  or   “truncation – possible loss of data”.  These warnings are there for a reason – correct the program syntax so that the code compiles with no warnings.

 

 

Department Standard:

 

--------------------Configuration: minmax - Win32 Debug--------------------

Compiling...

minmax.cpp

 

Linking...

 

minmax.exe - 0 error(s), 0 warning(s)

 

 

 

 

 
 


 

 

 

 

 

 

 

 

 

 

 

 

 

Nonstandard:

 

--------------------Configuration: minmax - Win32 Debug--------------------

Compiling...

minmax.cpp

minmax.cpp(22) : warning C4244: '=' : conversion from 'double' to 'int', possible loss of data

minmax.cpp(19) : warning C4101: 'i' : unreferenced local variable

minmax.cpp(25) : warning C4700: local variable 'min' used without having been initialized

 

Linking...

 

minmax.exe - 0 error(s), 3 warning(s)

 

 

 
 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 



NO “magic numbers”

 

Integer literals should be replaced by constant identifiers

 

Department Standard:

 

const int TAX_RATE = .073;

 

price = cost * (1 + TAX_RATE);

 

 

 

Nonstandard:

 

price = cost * 1.073;

 

 

 
 

 

 

 

 


 

 

 

 

 

 

 

Use “White Space”

 

Insert blank lines between declarations and statements and between blocks of related statements to make clear the structure of the program.

 

 Use a space before and after every operator or assignment symbol.

Department Standard:

 

x = y + 2 / z;

 

Nonstandard:

 

x=y+2/z;

 

 

 
 

 

 

 

 

 

 

 

Department Standard:

 

cin    >>  minimum;

cout  <<  setw(7)  <<  minimum;

 

 

 

 

Nonstandard:

 

cin>>minimum;

cout<<setw(7)<<minimum;

 
 


 

 

 


Other Programming Principles

 

 

Principle 1:     Programs and Functions should be well structured

 

a.                  Use a modular approach for a complex problems.

 

 

b.                  Use local variables within functions when the variable is used only within that function.

 

 

c.                  Use parameters to pass information to and from functions.  NO global variables.

 

 

d.                  To protect arguments that should not be modified by a function, declare the parameters to be value parameters or constant reference parameters rather than reference parameters.

 

 

e.                  Use accessor methods (get/set member functions) instead of public variables in objects.  All data members should be private.

 

 

f.                    Variables should not be reused for different purposes within the same function.

 

 

 

 

 

 

 

 


 

Principle 2:     All Source Code Should be Documented

 

a.                  Each program MUST include opening documentation.

 

 

b.                  Comments should be used only to explain key code segments when the meaning is not obvious.

 

 

c.                  Do not use documentation that restates the obvious.  It tends to serve no purpose other than to clutter the program for the reader.\

 

 

d.                  Strive for simplicity and clarity.  Clever programming tricks should be avoided when clarity is compromised.

 

 

e.                  Every effort should be made to make code clear through good design, simplicity, good naming and layout. Comments are required where code is not clear.

 

 

 

 

 

Principle 3:     Source Code should be Formatted in a Style that Enhances Readability

 

a)                 Insert blank lines between declarations and statements and between blocks of statements to make clear the structure of the program.

 

 

b)                 Declare constants and variables at the top of a function.

 

 

c)                  Label all output produced by a program.

 

 

d)                 Separate functions by a row of commented stars( //******)

 

 

 

 

 

 

A heading should appear at the beginning of each file of a program that conforms to the following format:

 

//******************************************************************************

//

//                      File:                             max.cpp

//                     

//                      Student:                      Sam Student

//

//                      Assignment:              Program #1              

//

//                      Course Name:           Programming 1 

//

//                      Course Number:        COSC 1540 - 01

//

//                      due:                             Dec 19, 2002

//

//

//                      This program asks the user to read a file

//                      of integers from a disk file and then

//                      determines the maximum of the                 

//                      three numbers.

//         

//                      Other files required:

//                                  1.         numbers.txt    –          text file of integers

//                                  2.         max.h –          prototypes for all functions

//                                                                                  needed by max.cpp

//                     

//                     

//******************************************************************************

 

 

 

 

 

All functions should be separated by a row of commented stars:

 

//******************************************************************************

 note:  department standards that differ from the text book are highlighted.