p1-recipes

EECS 183 Style Guide

Following consistent code style guidelines:

The code style in EECS 183 projects will be graded against the following guidelines:

Comments

  1. At the top of each file, include a comment with your (and your partner’s) name, your (and your partner’s) uniqname, and a small description of the program or file. This is included in all the starter code.

    /**
     * hello.cpp
     *
     * EECS 183: Project 0, Fall 2020
     *
     * Natalie Emcard
     * natalie@umich.edu
     *
     * Says hello to the world.
     */
  2. Add a comment describing code that would not be clear to you if you were reading it for the first time.
    // This comment is not necessary because the code is clear on its own:
    // Print out number the user enters
    int x;
    cin >> x;
    cout << "You entered: " << x << endl;
    
    // This comment is necessary:
    // Find the base 3 logarithm of x
    int log3 = 0;
    while (x > 1) {
        x /= 3;
        log3++;
    }
  3. Comments must be on their own lines.

    int y = 4; // this comment is bad style
    
    // this comment is good style
    int x = 3;
  4. It’s normal to comment out code you used for testing and isn’t needed anymore, but do not hand in code with commented-out regions.

     // bad style
     // Testing whether this algorithm works
     // for (int i = 0; i < 5; i++) {
     //    callFunction();
     // }

Whitespace and Indentation

  1. There must be single space between operators and their operands.
     // bad style
     count+=(a+b)*c/d+random();
    
     // good style
     count += (a + b) * c / d + random();
  2. There must not be a space around parentheses.
     // bad style
     pluralize ( "person" ,"people" , numberOfPeople );
    
     // good style
     pluralize("person", "people", numberOfPeople);
  3. There must be only one statement on each line.

     // bad style
     int x = 3; int y = 2;
    
     // good style
     int x = 3;
     int y = 2;
  4. There must be a line break after every {.

     // bad style
     if (x > 3) { y = 2; }
    
     // good style
     if (x > 3) {
         y = 2;
     }
  5. Indent your code in a consistent way that shows which blocks of code are inside others.

     // bad style
     int main() {
     int x = 0;
    
     if (x > 0) {
         cout << "x is positive." << endl;
         } 
     else { for (int i = 0; i < 3; i++) {
             cout << "*";
         }}
     return 0;
     }
    
     // good style
     int main() {
         int x = 0;
    
         if (x > 0) {
             cout << "x is positive." << endl;
         } else { 
             for (int i = 0; i < 3; i++) {
                 cout << "*";
             }
         }
         return 0;
     }
  6. No lines may be longer than 80 characters. Visual Studio and XCode have ways to show you how long your lines are. You can break long statements into multiple lines like this:
     // bad style
     cout << "a = " << a << " b = " << b << " c = " << c << " d = " << d << " e = " << e << " f = " << f;
        
     // good style
     cout << "a = " << a << " b = " << b 
          << " c = " << c << " d = " << d 
          << " e = " << e << " f = " << f;

Variables and Constants

  1. Variables must have names that describe their purpose. i and j used as loop counters do describe their purpose!
     // bad style
     int var1;
     int var2;
        
     // good style
     int num_students;
     int num_classes;
  2. Whenever possible, initialize variables in their declaration.
     // bad style
     int x;
     x = 2;
        
     // good style
     int x = 2;
  3. Use captialization for identifiers that matches the type of thing that is being identified.
    • Variables must either be “snake-case” like int course_credits = 4; or “camel case” like int courseCredits = 4;. Choose the one you prefer and use it consistently.
    • Constants must be in all capital letters like const int MAX_CREDITS = 18;.
    • Class names must have their first letter capitalized, like class CityBus { };.
  4. Do not use global variables. Global constants are acceptable.

  5. Magic numbers (numbers that do not have an immediately obvious meaning to another programmer) must be stored in constants. 0, 1, and 2 are never considered magic numbers.
     // bad style
     double area = 3.141592 * radius * radius;
        
     // good style
     const double PI = 3.141592;
     double area = PI * radius * radius;

Conditionals

  1. Test bool variables directly, not using expressions like == true or == false.
     // bad style
     // isValid is a bool
     if (isValid == true) {}
     if (isValid == false) {}
        
     // good style
     if (isValid) {}
     if (!isValid) {}
  2. In functions returning bool, simplify if/else expressions that compute the return value to expressions whenever possible.
     // bad style
     if (score1 == score2) {
         return true;
     } else {
         return false;
     }
        
     // good style
     return score1 == score2;

Loops

  1. Whenever you need temporary variables for iteration, use i, then j, then k, unless more specific names would make your code more readable.

     // can be good style
     for (int column = 0; column < numberOfColumns; column++) {
         for (int row = 0; row < numberOfRows; row++) {
             // do something
         }
     }

    If you find yourself in need of more than three variables inside a loop, you should reconsider your design!

Functions

  1. Every function you create must have an RME comment above it. The format of an RME comment will be described in lecture. If a function has a prototype (declaration), the RME must come before the prototype, not the definition.

  2. Very long functions must be broken into smaller functions. Try to limit your functions to 50 lines of code. This does not apply to main() in Project 1.

Other

  1. Do not use ignore() to get past characters in an input stream. getline() will cause far fewer problems.

  2. Do not use stringstream in EECS 183.

  3. C++ contains an exit() function that immediately exits your entire program. Do not call this function in any 183 projects. Your program must always exit naturally by reaching the end of your main function and returning.