CSCI 102 - Fall 2023 Fundamentals of Computation

Style Guide

When you write code, it is critical to ensure that code is readable and understandable to other humans. (Remember, when developing software correctness is your first goal, but a close second is making your code readable.) To that end you should always indent your code and comment your code.

Important note: Several points of your homework scores will be based on your indentation and commenting of your submission. Please ensure you follow this guide for each homework you submit.

Indenting Your Code

Indenting your code not only helps others to be able to read and understand it, but often helps you catch errors yourself. There is not just one way to indent your code but several conventions exist that programmers may adopt. The important thing is to pick a convention and apply it uniformly. Checkout Wikipedia’s Indentation Style page to see some conventions.

The key idea is that each time you start a nested set of curly braces ({...}) you should add one more tab stop. Initially, all your program code will go inside the main() function’s braces and thus all your code need only be indented (tab’d) one level. Below is a good example followed by a bad example:

• Good Example

  #include <iostream>
  using namespace std;

  int main()
  {
     int x = 5, y = 3;
     cout << "Hello world" << endl;
     cout << "1 + 1 = " << 1 + 1 << endl;
     cout << "Integer division means 5 / 3 = " << x/y << endl;
     return 0;
  }

• Bad Example (No Indentation)

  #include <iostream>
  using namespace std;

  int main()
  {
  int x = 5, y = 3;
  cout << "Hello world" << endl;
  cout << "1 + 1 = " << 1 + 1 << endl;
  cout << "Integer division means 5 / 3 = " << x/y << endl;
  return 0;
  }

• Bad Example (Uneven Indentation)

  #include <iostream>
  using namespace std;

  int main()
  {
     int x = 5, y = 3;
    cout << "Hello world" << endl;
       cout << "1 + 1 = " << 1 + 1 << endl;
     cout << "Integer division means 5 / 3 = " << x/y << endl;
   return 0;
  }

Note: All of these examples compile and run just fine. The compiler could care less about whitespace. In fact, there is an annual contest to see who can write the most obfuscated, but correct code.

As we learn more C/C++ language constructs such as if..else, while, and for statements also use curly braces {..}. Each time you start a new block with the open curly {, you should tab/indent the code one additional level. When you complete a block with }, you should dedent your code one level. Here are some examples:

• Good Example

  #include <iostream>
  using namespace std;

  int main()
  {
     int secret;
     cout << "Enter an integer: " << endl;
     cin >> secret;
     int guess;
     int low = 0, high = 0;
     cout << "Enter a guess: " << endl;
     cin >> guess;
     while( guess != secret ) {
        if(guess < secret){
           cout << "Too low!" << endl;
           low++;
        }
        else {
           cout << "Too high!" << endl;
           high++;
        }
     }
     cout << "Correct" << endl;
     return 0;
  }

• Bad Example (No Indentation)

  int main()
  {
     int secret;
     cout << "Enter an integer: " << endl;
     cin >> secret;
     int guess;
     int low = 0, high = 0;
     cout << "Enter a guess: " << endl;
     cin >> guess;
     while( guess != secret ) {
      if(guess < secret){
      cout << "Too low!" << endl;
       low++;
     }
     else {
       cout << "Too high!" << endl;
        high++
     }
     }
     cout << "Correct" << endl;
     return 0;
  }

Naming Variables

It is important to use good variable names. This often takes the place of having to write a comment (see below). Please use descriptive variable names:

Examples:

int numMonths; // Good!
int n;         // Bad!

double monthlyPayment; // Good!
double p;              // Bad!

Commenting

Commenting is also a critical part of writing software. While many developers wait until AFTER writing the code to comment it, it can be very helpful to comment AS you make decisions and to document your thought process.

You need not comment obvious things such as:

  int x = 5;  // Assign 5 to x

Instead, focus on:

• What does a loop (each iteration) represent from the more abstract problem.

  // keep guessing until the user is correct
  while( guess != secret ) {

  }

• Explaining the abstract meaning of an if statement or else if.

  // if random_value represents heads
  if( random_value <= 0.5 ) {

  }
  // else tails
  else {
    
  }

• Design decisions, alternative implementations, or assumptions.

  // Chose to repeat the calculation since it is faster than
  //  detecting duplication
  data[i] = (a+b)/2.0;

• A brief description of what the function or program does and any assumptions you make.

  // Validates all the numbers in the array are within
  //  the range [0 10) and returns the bool result.
  bool validateAllInputs(int data[], int len)
  {

  }