UMBC, CMSC202 Computer Science II, Spring 2007

CMSC 202 - General C++ Coding Standards

Every programming department has some set of standards or conventions that programmers are expected to follow. The purpose of these standards is make programs readable and maintainable. After all, you may be the programmer who maintains your own code more than six months after having written the original. While no two programming departments' standards/conventions may be the same, it is important that all members of the department follow the same standards. Neatness counts!!! The following standards are to be followed in CMSC 202.

Part of every project grade is based upon how well these standards are followed.

It is your responsibility to understand these standards. If you have any questions, ask your instructor, any of the TAs, or the Computer Science Help Center.

C++ File Extensions

There are numerous file extensions used to designate C++ source code files and header files. For this course, the file extensions .cpp for source code files and .h for header files will be used. No other extensions are permitted.

File Naming

For every project, a file containing only the main( ) function is required. This file should be named after the project and have a .cpp file extension. For example, the main( ) function for project 3 would be in a file named Proj3.cpp.
Auxiliary files (e.g Proj3Aux.cpp) and/or header files (e.g. Proj3Aux.h) are permitted, but must be named appropriately.

The executable for a project must be named after the project. For example, the executable for project 3 must be named Proj3 (notice the capital "P"). This is very important because the graders will look for that file to run your program. The graders will not run a.out or any other executable. The executable name is controlled by your makefile - get it right.

For most projects, you will be creating your own classes. In these projects, the following standards also apply.

Grading scripts used by the graders assume that you follow these convention.

File Organization

Class Definition Standards

The following standards must be followed when a class is defined within it's header (.h) file

Variable, Constant and Function Declarations

These standards detail how variables and constants should be declared, proper function prototype declarations as well as naming conventions.


The following sections detail the required program documentation. Failure to adhere to these standards will result in point deductions from your project submission.

Use of Whitespace

The prudent use of whitespace (blank lines as well as spaces) goes a long way to making your program readable.

Use of Braces


Comments are the programmer's main source of documentation.

From "The Practice of Programming" by Brian Kernighan and Rob Pike, page 23

Comments are meant to help the reader of a program. They do not help by saying things that the code already plainly says, or by contradicting the code, or by distracting from the code with elaborate typographical displays. The best comments aid the understanding of a program by briefly pointing out salient details or by providing a larger-scale view of the proceedings".
Rule of Thumb:
Approximately every 5 lines of code need AT LEAST 1 comment.
Not every line of code needs a comment.
Constant declarations MUST have 1 comment.

Commenting standards for files, functions, and code are described below.

File Header Comments

EVERY .cpp and .h file should contain an opening comment describing the contents of the file and other pertinent information. This "file header comment" MUST include the following information.
  1. The file name
  2. The project number
  3. Your name
  4. The date the file was created
  5. Your section number
  6. Your UMBC e-mail address
  7. A description of what the code in the file does
For example, /***************************************** ** File: Proj1.cpp ** Project: CMSC 202 Project 1, Fall 2005 ** Author: Bob Smith ** Date: 9/22/05 ** Section: 0304 ** E-mail: ** ** This file contains the main driver program for Project 1. ** This program reads the file specified as the first command line ** argument, counts the number of words, spaces, and characters, and ** displays the results in the format specified in the project description. ** ** ***********************************************/

Function Header Comments

Function header comments are the primary form of documentation for the user of our functions and classes. It is important that this documentation be both complete and accurate as it forms a "contract" between the function/class user and and the function/class implementer.

EACH FUNCTION and CLASS METHOD must have a header comment that includes the following information. The full function header comment described below must appear in the appropriate .h file. Less formal function header comments are required in the appropriate .cpp file.

  1. The function's name
  2. The function's pre-condition(s) (if there are no pre-conditions, say so).
  3. The function's post-condition(s).
A pre-condition is a statement giving the condition(s) that is (are) required to be true when the function is called. The function is not guaranteed to perform correctly unless the pre-condition is true (see text page 113). It is NOT just a restatement of the parameter names and types.
All functions must test for pre-conditions to the extent possible Until we learn about exceptions, if a false pre-condition can be handled in code, do so (see CircleArea function below).

A post-condition is a statement describing what will be true when the function call is completed (assuming the pre-condition is met and the function completes -- see text page 113).

For example, in Circle.h we would expect to find prototypes and full function header comments like this intended for the user of the function

//------------------------------------------------------- // Name: CircleArea // PreCondition: the radius is greater than zero // PostCondition: Returns the calculated area of the circle //--------------------------------------------------------- double CircleArea (double radius ): whereas in the .cpp file we expect to find the function implementation and comments meant for the programmer // CircleArea // Given the radius, returns the area double CircleArea ( double radius ) { const double PI = 3.14159; // handle unmet precondition if (radius < 0.0) return 0.0; else return PI * radius * radius; } Pre- and Post-conditions will be discussed in more detail in class.

In-Line Comments

CSEE] | [CMSC202] | [Spring '07 CMSC202]             Last Modified: 11 Feb 2007 01:04:15 EST