Southern Illinois University Edwardsville Logo
Apply to SIUE
Engineering Header

Programming Style Guidelines

Program Comments: A well-written computer program in a high level language, such as C/C++, is said to be "self-documenting". Through the use of meaningful identifiers and logical flow of computer instructions, a program you write should be "readable" to another programmer. However, a programmers intention of what the program does and how the program does it are not always easy to see by looking at the program. That is why it is important to include comments in your programs.

The style of your comments includes where you put comments in your program and what you say in those comments. There are many different comment styles. You should follow the one described below, unless your instructor indicates differently. The elements that are considered essential to your programming are emphasized by "must".

File and program header comments: Each program that you write must have a comment at the beginning of the program that is called "a header" or "header comment". This must include the following information: Your name, the date, the name of the file the program is stored in, a description of the program and usage (how to run it).

Example:

// File: prog1.cpp
// Name: Martha Reeves
// Date: 8/13/99
// Course: CS 150 - Introduction to Computing II
// Desc: Program calculates mean, standard deviations, and variance for a
// set of numbers.
// Usage: The program reads from a text file containing one number per line.
// The program prompts for and reads the name of the file.

As you develop your programming skills, you will divide your program into different files called modules. Each file must also contain a header comment that includes your name, the date, the name of the file in which the code is stored. You should also indicate what other files the module depends on.

Example:

// File: prog4.cpp
// Name: Martha Reeves
// Date: 8/13/99
// Course: CS 150 - Introduction to Computing II
// Desc: Program reads in a students course information into an array of courses. It
// calculates gpa and quality points. It then prints our a course report of the
// students credit hours, grade, quality points and gpa.
// Usage: The user types in one positive number. Other files required: course.cpp, course.h

An example of a header comment for a file containing a class implementation: