CMSC 202 Coding Standards

File Organization

The organization and structure of the files for a C++ program is important. Poorly organized files make code maintenance and debugging difficult. Here are the rules for file organization for projects:

Each class is to be defined in its own header file. The file extension must be .H or .h It's a good idea, but not required, to name this file after the class. For example, class Foo would be defined in a file named Foo.H or Foo.h
Every such header file is to be guarded using the
```
  #ifndef FOO_H
  #define FOO_H
        .
        .
  #endif
```
style. This style is used to avoid multiple includes of the header.
No method is to be implemented in a header file. Implementation belongs in the matching implementation file.
Each class is to be implemented in its own implementation file. The file extension must be .C or .CC or .cpp It's a good idea but not required to name this file after the class. For example, the Foo class would be implemented in a file named Foo.C or Foo.CC or Foo.cpp.

Note that each class has two associated files -- the definition or header file and the 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. Do include the header if it defines an entity referred to. Do not include it otherwise. For example, suppose Foo.h refers to an ostream entity and a string entity. Then, definitely do include iostream.h and mystring.h in Foo.h. Now, suppose the implementation file Foo.C refers to an ostream entity, but not a string entity. Then Foo.C should include Foo.h and iostream.h, but not mystring.h. Note that iostream.h is included even though its inclusion is also caused by including Foo.h. Guarded header files keep this from causing multiple definition and your code becomes cleaner and more readable.
The main function is to be in its own file. The file extension must be .C, .CC, or .cpp It's a good idea, but not required to name the file after the project. For example, the main function for project 3 would be in a file named Proj3.C, Proj3.CC or Proj3.cpp
The executable for a project must be named after the project. For example, the executable for project 3 must be in the proj3 file. 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. Do not submit your executable, the grader will construct it by using your makefile.

Documentation

Every file is to be headed by comments giving the name of the file, your name, the creation and current dates, and a brief description of the file's contents.

The header file for a class presents the public interface for the class. We adopt the convention that class documentation is done in the header file. Implementation files may be documented also, but this is documentation for the programmer, not for the class user.

For an example of header file documentation, see the sample header. You are encouraged to adopt this sample style. If you prefer your own style, that's ok, but it must meet the specifications laid out here.

Documentation of a class is to include the following information:

At the start of the definition, describe the class, the author (you), and the current version (a date).
At the start of each method or function describe
- The purpose of the method.
- The meaning of each parameter.
- Conditions that must be met for the method to operate correctly (pre-conditions).
- Conditions that are true when the method exits (changes made to internal variables, etc.) (post-conditions)
- The meaning of what is returned.
Data fields need not be documented since they are always private. You may document a data field if necessary for clarity.

Style

There is no universally-accepted coding standard for C++ programs. When you get that super high-paying job after graduation, you will most likely have to work to some coding standard. Most standards are arbitrary, but serve the important function of making your code more readable for others following the standard. Standards can also help in bug detection. Standards are good, but there is no one good standard.

For projects in this class, use the following coding standard:

Only one private, protected and public section in a class definition. public comes first, followed by protected and private, in that order.
Every data member of a class must be private.
Avoid global or file-scope variables. You may use const variables globally - nothing else.
Avoid macros (#define) for constants. Use const variables for constants.
If a class has any virtual methods, provide a virtual destructor.
If an accessor is provided for a data member, it must be a const method. Example:
```
int getSize() const
```
If a mutator is provided for a data member, it must return void. Example:
```
void setSize(int newsize)
```
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:
  const int MAXSIZE
- Class names begin with an upper-case letter. Join multiple words by capitalizing each one. Examples:
  class DoubleLinkNode
  class Matrix
- The names of functions, methods, ordinary variables, and parameters begin with a lower case letter. Join multiple words by capitalizing each one. Examples:
```
void setSize(int)
int inverse(int)
Matrix mat
int arraySize
```
- Class data members underscored and lower case. Example:
  int _length. Remember, all class data members must be private.

Makefiles

Every project must be submitted with an associated makefile. The makefile is to be named either Makefile or makefile, your choice. No other names are acceptable for your makefile.

The grader will compile your submitted project by typing 'make,' so your makefile must correctly make your project. This includes correct naming of the executable.

A number of tutorials on makefiles are available. One is the UCS tutorial. Another is an excerpt from the GNU tutorial.

Last modified on Monday Jan 22, 2000 by Dennis Frey
email: frey@cs.umbc.edu