You are responsible for reading and following these programming style guidelines. Points will be deducted from homeworks submitted that are difficult to understand, and better style yields programs that are easier to debug.
Readability normally takes priority over performance. You are not graded on execution speed. Intentional “bad” style to solve sluggish performance problems should be commented as such.
Keep your code lines at reasonable length. Delete all commented code before submitting your work.
Describe in details any new method you try to implement. A new method is one that was not presented in a lecture or in a homework assignment. If you got the idea from a paper or a website make sure you reference the source in your code.
Names: Give all classes, functions, variables, etc, meaningful names, for example "lineEndPoint" rather than "p". With easy copy and paste and auto-completion available, there is no serious reason to use short names.
In an Object Oriented Program (OOP), data is logically encapsulated in classes, which are created as objects at runtime. The work of the program is done by calling the methods (member functions) of the class to operate on the object's data. This is in contrast to a classic procedural program where the operating system calls a main() function, which does the work of the program sequentially. The C language supports only procedural programs, while C++ supports both OOP and procedural styles.
Some of the code supplied with the assignments is object oriented because many graphics paradigms fit the OOP model well. The assignment templates are C++ so you can choose a blend that you are comfortable with, provided your resulting program is readable.
The Visual Studio does a lot of formatting for you automatically as you type, and can apply auto-formatting to existing source text.
{}: Use a consistent pattern when locating curly braces and be sure closing curly braces } are lined up vertically with the start of their block. For example:
Bad:
bool MyFunc(int Number)
{
. . .
for (int j = 0; j < Number; j++) {
pixel[j] = 0;}
}
Good:
bool MyFunc(int Number)
{
. . .
for (int j = 0; j < Number; j++)
{
pixel[j] = 0;
}
}
or
bool MyFunc(int Number) {
. . .
for (int j = 0; j < Number; j++) {
pixel[j] = 0;
}
}
Indentation: Use a consistent amount of indentation for each code block level in your source code. For example:
Bad:
bool MyFunc(int Number)
{
. . .
for (int j = 0; j < Number; j++)
{
pixel[j] = 0;
}
}
Good:
bool MyFunc(int Number)
{
. . .
for (int j = 0; j < Number; j++)
{
pixel[j] = 0;
}
}
Whitespace: Use a blank line or 2 to separate logical divisions within source files. Some examples of logical divisions might be functions, class definitions, global variables, constants, #include directives, private class members.
One statement per line: Don't put multiple statements on one line. This creates problems stepping through your program during debug as well as degrades readability.
A code block is what is between a matching pair of {}, such as a function body, for loop, while loop, or if/else clause. Shorter code blocks are easier to understand and less prone to problems than long rambling sequences of statements. The common way to reduce block size is through the strategic use of functions.
Repeated code: Typing or cutting and pasting the same code in multiple places creates inconsistencies and bugs as you modify the code in one place and forget to fix it in another. Whenever you write essentially the same code two or more times, possibly with different values, make that block of code into a function and make the values into parameters.
Do exactly one thing: A function should do exactly one thing and its name should describe that thing. It could be a little thing, like a Degrees2Radians() one-liner, or it could be a big thing, like “DisplayScene()” that calls many other functions, but in any case, a function should express a single concept that can be ascertained from its name.
Fit in one screen: A good rule of thumb is to break up functions into smaller functions if they are too long to fit in one screen in the editor.
Limit arguments to 8: A rule of thumb is to limit the number of arguments to functions to no more than 8. Sometimes excessively long argument lists can be a hint that multiple data items might be better represented as a struct, array, or class, or that splitting code into smaller functions is not the best approach in this case.
Don't overdo it: There are no hard rules on how to divide code into functions, you must use educated judgement. Sometimes you have a long series of things to do on the same data and it doesn't make sense to force the sequence into small functions. Excessively long argument lists or heavy use of global variables at file scope can be signs that you are overdoing it.
Identify logical divisions within files: Some examples of logical divisions might be groups of related class definitions, global variables, global constants, groups of helper functions.
Describe what the code does: Don't repeat what is obvious in the code. Describe what the code contributes to your solution. For example:
Bad (Comments don't give any information that couldn't be gathered from the code):
// Increment j from 0 to the buffer length
for (int j = 0; j < BufferLen; j++)
{
// Set the jth pixel to zero
pixel[j] = 0;
}
Bad (Comment still doesn't give any context of what's happening):
// Set every pixel to zero
for (int j = 0; j < BufferLen; j++)
{
pixel[j] = 0;
}
Good:
// Color the pixel buffer black
for (int j = 0; j < BufferLen; j++)
{
pixel[j] = 0;
}
Identify unconventional ways of doing things: For example:
// Scanning pixel array from right to left instead of the left to right to make loop termination test simpler and faster
// Changed from formula in class notes to accommodate negative angles
Not a substitute for readable code and meaningful names: If you find yourself writing lengthy comments explaining what you are doing, maybe you should think about rewriting your code.
More isn't always better: You don' need to comment every line of code. Too many comments can confuse the reader and are harder to keep synchronized with changing code.
Cite sources: For example:
// Adapted from algorithm found on herberts_graphics_tricks.com