YALE UNIVERSITY
DEPARTMENT OF COMPUTER SCIENCE
| CPSC 427: Object-Oriented Programming | Handout #3 |
Professor M. J. Fischer | | September 5, 2018 |
|
|
|
|
This document describes some of the local coding standards for use in this class. If you don’t
agree with the standard or don’t understand what it says or why I think it’s important, then
please ask.
The standards are arranged by severity levels, where violation of “F” rules will result in the
greatest loss of points and “C” rules the least.
1 Level-F errors: Constructs to Avoid
If you believe that you MUST disobey one of these rules, ask for permission.
- Do not use goto.
- Do not use global variables. Global constants are OK.
- All class data members (and some functions) should be private.
- Use C++ iostreams, not C stdio, for input and output.
- Use only the 2017 standard C++ language – no proprietary functions or include files
such as are found in Visual C++.
- Your code must compile on the Zoo without errors.
- Structure your source code appropriately into header files (.hpp) and implementation
files (.cpp).
2 Level-D errors: Functionality
These are very basic rules.
- Your code must compile on the Zoo without warnings when using the required -O1
-g -Wall -std=c++17 compiler flags.
- Insofar as possible, test every line of code in your program.
- Check for I/O errors routinely, especially for files that do not open properly.
- File system path names are not portable and should not be used in your program.
To tell the compiler to look in non-standard places, use the -I and -L compiler flags.
These flags should be put in your Makefile when needed. If for any reason you must
write a path name in your program, put it in a #define or a const declaration at the
top of main so that it can be found and changed easily.
3 Level-D errors: Indentation and Whitespace
Any time you take a job, you must learn the local coding standards and follow them. These are
the standards for this class.
- Use this style for indentation and brackets. Note that the opening { is at the
end of one line, not at the start of the next. Note also the convention of leaving
spaces around function arguments (as in inRange( ageIn )) but not around
the Boolean expression that appears within the parentheses for if and while
statements.
while (k < numItems) {
cin >> ageIn;
if (inRange( ageIn )) {
age[k] = ageIn;
k++;
}
else {
cout << "An invalid age was entered, try again.");
}
}
- Set your indentation amount to 4 columns. Never let comments interrupt the flow of the
code indentation.
- Confine all code and comments to 80 columns. Break up long lines of code into parts at
logical break points. Do not let them wrap around from the right side of the page to the
left edge of the page on your listings.
- Make your work look professional: clear, neat, and well-organized. Do not turn in work that
is full of commented-out code.
- Use whitespace to make the code easy to read. Use blank lines to break the code into
paragraphs of related actions. Do not put a blank line between every line of your code.
Generally put a blank space after a semicolon or around a binary operator, e.g., x
= y * -z;, but it’s okay to omit the spaces when it improves readability, e.g.,
x*x + y*y.
4 Level-C errors: Semantics and Organization
- Simplicity is good; complexity is bad. If there are two ways to do something, the more
straightforward or simpler way is preferred.
- Clean up after yourself. If you allocate dynamic memory with new, free it with delete.
Explicitly close all files that you have opened.
- Learn to use the names of the various zero-constants appropriately. nullptr is a
pointer to nowhere, ’\0’ is the null character, "" is the empty string, false is a bool
value, and 0 and 0.0 are numbers. Use the constant that is correct for the current
context.
- If a function is simple and fits entirely on one line, write it that way. Example:
bool squareSum( double x, double y ) { return x*x + y*y; }
- Otherwise, each function definition should start with a whole-line comment that
forms a visual divider. If the function is nontrivial, a comment describing its purpose
is often helpful. If there are preconditions or postconditions for the function, state
them here.
- Keep all functions short. With rare exceptions, a function should be no longer than
one screen. Ideally, the function should be shorter than a dozen lines. Break up long
or complex chunks of logic by defining more functions.
5 Level-C errors: Style Standards.
- Please do not use i, I, l, or O as a variable name because i and l look like 1, and O
looks like 0. Use j, k, m, or n instead.
- Long, jointed names and short, meaningless names make code hard to read. Try for
moderate-length names, 3 to 8 characters. Local variables and private class members
should have short names because they are always used in a restricted context. Longer
descriptive names are appropriate for non-local names such as global constants and
class names.
- Do not use the same name for two purposes (a class and a variable, for example). Do
not use two names that differ only by an ’s’ on the end of one. Do not use two names
that differ only by the case (for example Object and object).
- #include "tools.hpp" in each module. Call banner() at the top of main(), call
bye() at the end, and call fatal() to handle fatal errors until we introduce exceptions.