Good Practices Checklist

There are many details that makeup a good program, and that meets the characteristics that we discuss in the course. The following is just a start towards listing them. The grade for an OOP project is partially based on the items in these checklists.

Creating a list of these is not easy as there are always exceptions. However, these exceptions are not common. Think about where this would apply, not what the exception would be.

The checklist will be updated as we go along in the course.

Overall Program

Statement Level

prefer:

 int total = 0;
 for (auto element : v) {
 	total += element;
 }

over

int total = 0;
for (int i = 0; i < v.size(); ++i) {
	total += v[i];
}

Functions

/**
 * Average of the values
 *
 * @param n1 First value
 * @param n2 Second value
 * @return Average of the two values
 */
double average(int n1, int n2);
 
/**
 * Set the filename attribute for the srcML
 *
 * @param filename Name of a file
 * @retval SRCML_STATUS_OK on success
 * @retval SRCML_STATUS_INVALID_ARGUMENT
 */
int srcml_set_filename(const char* filename);

Make sure to describe the parameters, and return values, especially if error codes are used

std::string

 std::string s = "";

just declare the string:

 std::string s;
 if (s == "")
 	;

just check that it is empty, just like other containers:

 if (s.empty())
 	;

One exception might be if you are in a set of if statements (such as a nested if) and are comparing the string to other literal strings.

Also, if you need to change to value to an empty string, instead of:

 s = "";

just clear out the data, just like other containers:

 s.clear();

Parameter types

Direction Primitive Object
in T const T&
out, inout T& T&

Examples:

   int n
   const std::string& s
   int& total
   std::string& palindrome

As always, some specific cases:

return types

Type Application
T Return copy of local variable or field
const T& Return read-only reference to field

Examples:

   int sum()  const { return total; }
   const Shape& currentShape() const { return shape; }   
   Shape genShape() { Shape s; /* ...  */ return s; }

Classes

Comments

# Debugging Output

Prefer:

  std::cerr << "Got to this line in the program!!!\n";

to:

  std::cout << "Got to this line in the program!!!\n";

Write any debugging messages to std::cerr, not std::cout. First, the program already uses std::cout for output. Second, std::cerr is not buffered, while std::cout is. Why does this matter? If your program exits, unbuffered output may be lost. So you may not see your debugging messages.