docs

EECS 183 Style Guide

Following consistent code style guidelines:

Helps other people read and understand your code
Helps you make fewer mistakes
Is important when more than one person is working on a project

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

Comments

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 2023
 *
 * Natalie Emcard
 * natalie@umich.edu
 *
 * Says hello to the world.
 */
```

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++;
}

Comments must be on their own lines.

int y = 4; // this comment is bad style

// this comment is good style
int x = 3;

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

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();

There must not be a space around parentheses.

 // bad style
 pluralize ( "person" ,"people" , numberOfPeople );

 // good style
 pluralize("person", "people", numberOfPeople);

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;

There must be a line break after every {.

 // bad style
 if (x > 3) { y = 2; }

 // good style
 if (x > 3) {
     y = 2;
 }

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;
 }

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

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;
```

Whenever possible, initialize variables in their declaration.

 // bad style
 int x;
 x = 2;
    
 // good style
 int x = 2;

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 { };.
Do not use global variables. Global constants are acceptable.
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

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) {}

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

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

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.
Very long functions should 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

Do not use ignore() to get past characters in an input stream. getline() will cause far fewer problems.
C++ contains an exit() function that immediately exits your entire program. Do not call this function in any 183 projects 1-4. Your program must always exit naturally by reaching the end of your main function and returning.