This document describes the general guidelines for designing programs in my CSC 160/161 classes. Please note these two disclaimers:

1.      These are guidelines, not laws of nature

2.      These guidelines are tailored for beginning C++ students. Yes, there are other methodologies, but the intent of these guidelines is to get C++ programming students headed in the right direction.

Enjoy... yow, bill

Design

This section is very brief on a very substantial topic.

The design of your C++ program consists of two primary parts:

1. Class definitions
2. Pseudo-code for class member functions or other functions (like main) that are complex

Some general pointers:

• Your classes should generally be flexible and usable by others
• Your classes should be consistent with a common interface across functions and consistent naming conventions
• Provide get/set functions to access member variables, as needed
• Sometimes writing pseudo-code as comments in your function(s) is an easy way to both design and comment your code
• Create header (*.h) files for each class and compile your class definition before actually implementing all the member functions
• Don’t start coding before knowing how to solve the problem… the answer is not in the screen.
• Your design may need to change… so be it!

Implementation Quality Checklist

A high-quality C++ implementation consists of many things. Some things are very tangible, like the presence of good comments. Others are harder to quantify, like an aesthetic overall design. This section focuses on the first indication of code quality, tangible things that should be in your program implementation.

Here are some of the guidelines for good C++ implementation:

#1. File header comments

At the top of each file, document your name, the file name, creation date, and a short description of what the file contains.

#2. Function header comments

Before each function, document the function name, short description of what the function does, its input (parameters) and output (return value and any side effects). Also, the function comment should stand out from the rest of your code so that it is easy for the reader to scan the page for functions.

#3. Function prototypes

If it is nontrivial, very briefly describe the purpose of a function prototype. Leave the details of the description for the function header comment described above.

#4. Variable comments

For each variable, briefly describe the purpose of the variable. This is an important rule for beginning programmers that you may relax after some programming experience.

#5. Block comments

A “block” of code is a group of C++ statements that accomplishes some higher task. You should make special mention of anything tricky or abnormal about the section. These are often the most valuable comments in a program.

#6. Useful comments

Your comments should describe what your program does at a higher level. Don’t explain C++ in your comments; this is a very common mistake when you are learning the language. You can assume that your reader knows C++, so comments like “increment j” or “a class member variable” don’t add to your program’s readability.

#7. Pick a name style

There are two predominant naming styles used in C++ to separate words in a single name: underlines or capitalization. For example, a variable containing a “file name” may be named file_name or fileName. Do not mix styles; I prefer capitalization myself.

#8. Select good names

It is important to select meaningful names of things (variables, functions, classes, etc) in your C++ program. Also, use the following conventions regarding names:

·        Function names – start with a lower case letter… example: getInput()

·        Variable names – also, start with a lower case letter… example: myFile

·        Class names – capitalize class names… example: Rectangle

·        Constants – make all letters upper case… example: MAX_SIZE

#9. Indentation

Each new block (beginning with a curly brace) should be indented some reasonable (3-4) number of spaces, and you should be consistent throughout. If you use the automatic indentation provided by Microsoft Visual C++, you’ll be fine.

#10. All of the above

I don’t have a #10, but it seemed better than stopping at #9.

Testing

In our class assignments, we won’t do nearly the testing that a real program would undergo. For our assignments:

• Bad user input – the user should get a reasonable error message when he/she makes an improper selection in your program.
• Normal usage – try out a variety of “normal” cases exercising your program.
• Limit cases – try peripheral cases like the smallest acceptable values and the largest. Often, this is where your program will have difficulties.