CS2141 Style Guidelines

Comments

Each file and routine needs to begin with a block of comments. The goal of these blocks is to allow another programmer who is not familiar with your code to understand the purpose of your program.

File headers

Each file in the program must start with a header that includes:

• The filename
• A brief description of what is in the file
• Your name
• Your section
• The name of the assignment

//******************************************************************
// The name of this file
//
// Documentation, "Pointers" to where this file is discussed in
//     external documentation, if at all.
//
// Your name
// CS2141 Your Section
// Program name
//
// History - Include comments here about when different aspect
//     of this file were completed, changed, ...
//******************************************************************

Notice that there are comment seperators that use this char, *, to separate a block of comments. Each seperator must of the same length.

Function headers

Each function needs to begin with a header that includes:

• The name of the function
• A description of the function including its purpose and what it does.
• A list and description of any parameters.
• A list and description of any return value.

//******************************************************************
// Foo
// Describe this function
// List any parameters
// List any return values
//******************************************************************
void Foo (){
    ...
}

Class headers

Similarly, each class should begin with a header that describes what the class is for, and class methods and data members generally should have some short description, either in the header block or in the class definition itself:

//******************************************************************
// class Cow
// Describe this class
//******************************************************************
class Cow
{
public:

    Cow( );    // Default constructor

    void eatHay( int amount );  // This cow eats the given amount of hay
    void moo( );                // This cow moos.

private:

    int age;  // Age of this cow
};