Date: Mon, 11 Nov 1996 17:11:06 GMT Server: NCSA/1.5 Content-type: text/html Last-modified: Wed, 11 Sep 1996 19:05:54 GMT Content-length: 11956
Think of your source code as a document describing your implementation. Like writing a paper, article, or blueprint, you have the freedom to make choices regarding how to present your document. However, you also know that if you stay within the guidelines of popular convention for the type of document you are creating, then people reading your document will have an easier time understanding it. There is a tension between your creative freedom and the conventions dictating your style. It is your responsibility to find an appropriate balance.
// Program 0: The Bean Counter int main () { int number_of_beans; // Number of beans (from user) const double bean_weight = 2.051; // Average bean weight in grams cout << "Please enter the number of beans" << endl; cin >> number_of_beans; if (number_of_beans >= 0) { cout << "Number of Beans: " << number_of_beans << endl; cout << "Average Weight: " << bean_weight << endl; cout << "Total Weight: " << number_of_beans * bean_weight << endl; } | } | | | | | | | | | | +---- Level 2 (indented eight spaces) | | | +-------- Level 1 (indented four spaces) | +------------ Level 0 (not indented)I don't care how much you indent, but you must be consistant in your indenting. If you indent two spaces from level 0 to level 1, you must indent two more spaces from level 1 to level 2. Furthermore, if you indent two spaces anywhere in your code, you must indent two spaces everywhere in your code.
if (beans == bacon) { beans++; bacon++; }if/else
if (beans == bacon) beans++; else bacon++;while
while (beans == bacon) beans++;do while
do { beans++; } while (beans == bacon);switch (#1)
switch (number_beans) { case 0: cout << "What? No beans???" << endl; break; default: cout << "Ahhhh" << endl; break; }switch (#2)
switch (number_beans) { case 0: cout << "What? No beans???" << endl; break; default: cout << "Ahhhh" << endl; break; }
Option 1
header { body body }Option 2
header { body body }Option 3
header { body body }
// Function: Eat_Beans // Description: Notice how there are two blank lines between this // function and the next function. void Eat_Beans (void) { cout << "Burp!" << endl; } // Function: Count_Beans // Description: Notice how the two logical steps of the algorithm // are separated using blank lines. int Count_Beans (Carton carton) { // Sample the beans database to get the average weight int i; double average = 0; // Average weight within sample for (i = 0; i < SAMPLE_SIZE; ++i) average += beans_database[rand() % NUM_BEANS].weight(); average /= SAMPLE_SIZE; // Return total number of beans in carton int total_beans = int (Carton.weight() / average); return total_beans; }
// Do it like this: int i = 5 + 8 * (9 - 3); cout << "Hi"; // Not like this: int i=5+8*(9-3); cout<<"Hi";But some operators, like ++, [] and unary -, generally do not take horizontal whitespace.
// Do it like this: beans[i++] = -j; // Not like this: beans [ i ++ ] = - j;
// Program 0: The Bean Counter // Name: Gregory C. Sharp // Class: CS 302 Section 99 // Date: Jan 1, 1999 // E-Mail: greg@cs.wisc.edu // // Description: This program calculates the number of navy beans // in the known universe based on a user's estimate // of the universal navy bean constant.
// Program 0: The Bean Counter // File: Bean.h // Description: Class definition of the Bean class.
// Function: Count_Beans // Inputs: Weight of beans (in tons) // Outputs: Number of beans // Description: Calculates the number of beans based on the // average weight of a navy bean at sea level. int Count_Beans (double weight) { return int (weight / Bean::Average_Weight()); }A related group of small functions can share a single comment.
// Function: User Input Routines // Description: These utility routines control simple user inputs. int getInt (char *prompt) { int i; cout << prompt; cin >> i; return i; } char getYN (char *prompt) { char c; cout << prompt; cin >> c; while (c != 'n' && c != 'N' && c != 'y' && c != 'Y') { cout << "You fool. You enter Y or N! "; cin >> c; } return c; }
double weight; // weight of beans (in tons) double mass; // mass of beans (in kg)However, temporary variables, loop variables and input variables should not have a comment.
int i; // Loop variable doesn't need a commment! for (i = 0; i < NUMBER_OF_BEANS; ++i) { double d; // Input variable doesn't need a commment! cin >> d; bean[i].set_weight (d); }
The following is an example of a function which contains embedded comments.
// Function: Count_Beans // Description: First take a sample of the beans database to aproximate // the weight, and then use this to estimate the total number // in the carton. // Return the number of beans. int Count_Beans (Carton carton) { // Sample the beans database to get the average weight int i; double average = 0; // Average weight within sample for (i = 0; i < SAMPLE_SIZE; ++i) average += beans_database[rand() % NUM_BEANS].weight(); average /= SAMPLE_SIZE; // Return total number of beans in carton int total_beans = int (Carton.weight() / average); return total_beans; }
// Do it like this: double starting_location, time, velocity; double location = starting_location + time * velocity; // Not like this: double s, t, v; double l = s + t * v;But on the other hand, you should use short (1 letter) identifiers for temporary variables, loop variables and input variables.
// Do it like this: int i; for (i = 0; i < MAX_BEANS; i++) beans[i] = new Bean; // Not like this: int current_bean; for (current_bean = 0; current_bean < MAX; current_bean++) beans[current_bean] = new Bean;And finally, please use all capital letters for constants.
// Do it like this: const int MAX_BEANS = 100; // Not like this: const int max_beans = 100;