Coding standards, including formatting and documentation, are important because the human reader is one of the most important users of program source.
Main purposes of documentation include helping the reader to finds section of code and enabling the reader to understand code faster.
Secondarily, documentation can be useful in helping the reader to understand something that is not clear. If a large amount of explanation is required, it may be better to rewrite the code.
These rules have been set up to create the most clarity while reducing redundant documentation as much as possible.
Corrections and suggestions are invited.
Main program documentation #include statements symbolic constants function prototypes main program functions
Class definitions will generally go in their own files, but shouid precede function prototypes if used in a single compilation unit.
Global variables are often a bad idea, but should follow function prototypes if used in a single compilation unit.
This applies to comments as well as code.
/******************************************************************** Class: CSCI 480-2 Program: Assignment 1 Author: Your Name Z-number: z1234567 Date Due: mm/dd/yy Purpose: A short indication of what the program does, e.g.: Read and format relevant data from /proc file. Execution: Command to execute your program (should match directions on assignment sheet) ./hw1.exe [filename] If filename is omitted, /proc/xxx is used. Notes: (optional) any special notes to your T.A. or other readers *********************************************************************/
avg_height
.avgHeight
.avg_height
.avg_height
rather
than h
or hgt
.height
is preferable to hgt
.
Abbreviations can be useful for long or frequently repeated
words.
avg_height
for average height, then you should use
avg_weight
for average weight and not ave_
or average_
.
xyz_ptr
or addr_of_xyz
.for (i = 0; i < 10; i++) ...
const int MAX_STU = 40;
count_lines()
.// some comment // more comments // even more comments
This form is also acceptable and can be more convenient for doc boxes at the top of a program or function.
/* some comment more comments even more comments */
The following examples show the size of chunk that should be commented.
// Loop to accept and process user-supplied glucose measurements // Decide if gizmos or widgets are to be used // Calculate and store averages and standard deviations of measurements
Some programs are longer or more complex than others. That means that main() may have several sections while a function that only does one thing may have only one.
Occasionally, for a complex formula, a section will be only one line long:
// calculate the area of the triangle: semi is semiperimeter // s1, s2, and s3 are sides area = sqrt(semi * (semi - s1) * (semi - s2) * (semi - s3));
If you find yourself frequently needing such comments, you should consider changing your nesting style.... } // end I/O loop
// Item subtotals int tot_items; float tot_cost;
Horizontal alignment of variable names, as in the above examples, is encouraged but not required.
The following method is recommended:
if (condition) { statement1; statement2; } else { statement3; statement4; } while (condition) { statement 1; statement 2; }
If you use method 1, indent two spaces as shown.
Methods 2 and 3 are less desirable since they do not show indentation as clearly. If you use methods 2 or 3, two spaces are preferred; four is acceptable.
if (condition) { statement1; statement2; } else { statement3; statement4; } while (condition) { statement 1; statement 2; }
if (condition) { statement1; statement2; } else { statement3; statement4; } while (condition) { statement 1; statement 2; }
Other brace styles put the opening brace on the same line as the
if, else or while.
These are more difficult to read because opening and closing braces
do not line up.
These are permitted if you are used to them and prefer them.
Anyone who thinks that their preferred style is the only style or only logical style are encouraged to consult an exhaustive list of possible brace styles before making this assertion.
int fn(long_name1, long_name2, ..., long_name99)
Similarly, arithmetic expressions that overflow should be aligned under the preceding arithmetic symbol (+, etc.).
Likewise, I/O statements (cin
or cout
) statements that overflow should be aligned under
the preceding I/O operator (<<, >>).
Spaces are better than tabs for indenting because they will display correctly in any configuration.
Any good editor will have a setting that prevents spaces from being converted to tabs.
If you use tabs, you are responsible for making sure your program will display correctly on turing/hopper. Unix defaults to tabs every 8 characters.
for (i = 0; i < 10; i++)
total = calcTotal(amt, taxRate, tip);
/*************************************************************** Calculate the area of a triangle using Hero's formula Arguments: sides of the triangle Returns: the area of the triangle -1 if the lengths do not represent a valid (closed) triangle Additional section documentation as required. ***************************************************************/
/*************************************************************** Getters for class_name ***************************************************************/
xyz.h
,
where xyz
is the name of the class or a logical
variant thereof./**************************************************************** Class_name header (or description of resources in header) Author: Your Name Z-number: z1234567 Description: purpose of the class (optional) Any other information needed by the user ****************************************************************/
public
and private
.xyz.cpp
,
where xyz
is the name of the class or the same logical
variant as the header file./**************************************************************** Class_name Author: Your Name Z-number: z1234567 Description: purpose of the class (optional) Any other information needed by the user ****************************************************************/
# Course: CSCI 480-2 # Program: Assignment 1 # Author: Your Name # Z-number: z1234567 # Date Due: mm/dd/yy # Notes: (optional) further notes if needed