Many details make up a “good” program. The following is just a start towards listing them. The items below are considered in the grading of a class project.
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 extended as the semester progresses.
Do not use using namespace std;
.
using namespace std; cin >> n;
Instead, use the prefix for everything in a namespace:
Use the following naming convention:
Category | Semantics | Convention |
---|---|---|
Classes | things not actions | PascalCase |
Fields/Variables/Parameters | things | camelCase |
C++ Methods/Functions | actions | camelCase |
C Functions | actions | under_score |
Constant scalar values, e.g., int , double |
things | UPPERCASE |
C-Preprocessor/cpp variables, e.g., INCLUDE_XML_HPP |
things | UPPERCASE |
std::vector
, etc, follow that naming convention.XMLBuffer
Single-letter variable names are not to be used, except in certain, well-understood situations:
Name | Purpose |
---|---|
i , j , k |
loop-control variables |
c |
general character |
s |
general string |
n |
general int |
x |
general double |
Initialize temporary variables (those with local scope) when declared whenever possible. Prefer:
over:
Exception: Temporary variables initialized as an argument in a call:
int
as the standard C++ integer type. Possible exceptions: size_t
, std::size_type
double
as the standard C++ floating-point number type. There is hardly any reason to use float
.Comment each section of code on the line before
const
whenever possibleauto
when initializing a declaration that includes a call, e.g., auto pc = buffer.begin()
Use an explicit type instead of auto
when initializing with a literal value to make certain you get the intended type
Favor range-based for instead of direct indexing (or iteration). Exception: If comparing or changing multiple parts of the container in the array
prefer:
over
Prefer pre-increment over post-increment, i.e., prefer ++i;
over i++;
. Pre-increment is easier to understand, explain, and implement, e.g., post-increment is often implemented using pre-increment, and especially when these operators are overloaded:
This also applies to pre-decrement and post-decrement
@param
For each parameter@return
For the general return purpose@retval
Specific return values, e.g., error or status codesThere is much more, so feel free to experiment. However, be consistent.
inline
specifier. First, the compiler can ignore it. Second, the compiler automatically inlines small functions. Third, it is overused. The inline
specifier has valid purposes, but not only in specific cases and not in this course. Note: Do not confuse the general programming term “inline a function” or “inline a method” with the inline
specifier.The std::string default constructor initializes to an empty string. So instead of:
just declare the string:
A std::string is a (specialized) container. Use container methods over comparison. So instead of:
just check that it is empty, just like other containers:
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:
just clear out the data, just like other containers:
Direction | Primitive | Object |
---|---|---|
IN | T | const T& |
OUT, IN/OUT | T& | T& |
Examples:
As always, some specific cases:
const int
, is not in the list. The reason is that the const
is an unnecessary restriction for the function/method definition, and does not change the arguments allowed.T
)std::string&&
, separatelyThe following applies to all comments, except file header comments.
Terms to leave out of comments:
Phrases referring to program structure to leave out of comments:
General phrases to leave out of your comments: