CMSC 202 - OOP Coding Standards

CMSC 202 OOP Coding Standards

These coding standards deal specifically with C++ programs that use classes.

File Organization

There are five types of files associated with every project that contains one or more classes:
- A file containing only the main function. This file should be named after the project and have a .C file extension. For example, the main function for Project 3 would be in a file named proj3.C.
- A file containing the prototypes for all non-member functions. Give this file a descriptive name and a .H file extension.
- A file containing the implementations for all non-member functions. Give this file the same name as its corresponding .H file, but use a .C extension.
- Header files containing class definitions, one class definition per file. Name each file after the class it contains and give it a .H file extension.
- Implementation files corresponding to each class definition (.H) file. Name each file after the class and give it a .C file extension.
Every header file must be guarded using the
```
  #ifndef FOO_H
  #define FOO_H
        .
        .
  #endif
```
style. This style is used to avoid multiple inclusions of the header file.
No member function is to be implemented in a class header file (i.e., do not in-line any member function). All implementation belongs in the matching implementation file.
A header file is to be included in a given file if and only if the header defines an entity referred to in the given file. For example, suppose the header file Foo.H refers to an ifstream entity and a string entity. Then, definitely do include fstream.h and string.h in the Foo.H. Now, suppose the implementation file Foo.C refers to an ifstream entity, but not a string entity. Then Foo.C should include Foo.H and fstream.h, but not string.h. Note that fstream.h is included even though its inclusion is also caused by including Foo.H. Guarded header files keep this from causing a multiple definition error and your code becomes cleaner and more readable.
The executable for a project must be named after the project. For example, the executable for Project 3 must be in the Proj3 file (notice the capital "P"). This is very important because the grader will look for that file to run your program. The grader will not run a.out or any other executable. The executable name is controlled by your makefile - get it right.

Documentation

Every file, whether a .H or .C file, must contain a file header comment as described in the General C++ Coding Standards.

The header file for a class presents the public interface for the class. Therefore, we adopt the convention that class member function header comments are done in the header file. However, implementation file member function bodies should still contain comments.

For an example of header file documentation, see the heap.H file that was given to you for Project 2. You are encouraged to adopt this sample style. If you prefer your own style, that is acceptable, but it must meet the specifications laid out here.

Style

Only one private, protected and public section in a class definition. public comes first, followed by protected and then private.
Place friend function prototypes before the public section.
The friend designation is to be used judiciously. You should not use friend simply to avoid using the proper accessor and mutator functions. Projects which abuse friend will lose points proportionate to the degree of abuse.
Every data member of a class must be private.
You may use global symbolic constants (const), but not global variables.
Use const for constants, not #define.
Every class must define a default constructor, even if it does nothing.
Every class must define a destructor, even if it does nothing.
Every class must define an overloaded stream insertion operator.
Every class that contains one or more dynamically allocated data members must define an appropriate copy constructor.
If a class has any virtual methods, provide a virtual destructor.
If an accessor is provided, it must be a const method. Example:
```
     int getSize() const;
     void printSum() const;
```
Here are some suggested naming conventions. The important thing is that your naming is consistent. Following these conventions will help consistency. If you don't like these, adopt your own, but be consistent.
- Constants all upper-case. Example:
- Class names begin with an upper-case letter. Join multiple words by capitalizing each one. Example:
- The names of member functions begin with a lower case letter. Join multiple words by capitalizing each one. Example:
- Class data members begin with an underscore and are lower case. Example: