Code Readability Guidelines

Follow these guidelines, and you'll have prettier code. Your grades will look better, too!

Naming

Name your variables appropriately.

Humans are not Computers.

TAs are a subclass of Humans, and so are You. Use good naming practices!

Good Example

float quadraticFormula(float a, float b, float c) {
  float top = b * b - sqrt(4 * a * c);
  float bottom = 2 * a;
  float result = top / bottom;
  return result;
}

Bad Example

float Qf(float a, float b, float c) {
  float t = b * b - sqrtf(4 * a * c);
  float bm = 2 * a;
  float r = t / bm;
  return r;
}

Casing Recommendations

File names should be styledlikethis.
Class and Struct names should be StyledLikeThis.
Variable and Function names should be styledLikeThis.
Constants and Macros should be STYLED_LIKE_THIS.

Whitespace

Indent your code.

Indents make your code much more readable. It also helps you keep track of scope and avoid nasty little typos!

Use newlines to denote sections of code.

If your code can be broken into smaller sections (or even better—well-named helper functions), do it!

Good Example

int getFibonacciAt(int index) {
  if (index == 0) return 0;
  if (index == 1) return 1;

  int num1 = 0;
  int num2 = 1;
  int num3 = 1;

  while (index > 2) {
    int prevNum3 = num3;

    num3 = num1 + num2;
    num1 = num2;
    num2 = prevNum3;

    index --;
  }

  return num3;
}

Bad Example

int getFibonacciAt(int index) {
if (index == 0) return 0;


if (index == 1) return 1;
int num1 =           0;
int num2 = 1;




int num3 = 1;
    while (index    > 2) {
int prevNum3 = num3;
num3 =       num1 + num2;
num1 =   num2;
num2 = prevNum3;
            index --;
}
               return
num3;
}

This is only slightly exaggerated. Students have submitted worse! 😪

Comments

Comments make your code more readable and maintainable.

Good Example

// Levenshtein edit distance. Calculates the minimum
// number of changes (removing, adding, or substituting
// a character) required to make one word the same as
// another word. Is case sensitive.
int led(std::string word1, std::string word2) {
  // Get the length of the two words for future use.
  int len1 = word1.size();
  int len2 = word2.size();

  // If either word is empty, then the edit distance
  // is the length of the other one.
  if (len1 == 0) return len2;
  if (len2 == 0) return len1;

  // Obtain the cost of editing the last character of
  // either string.
  bool lastCharsEqual = word1[len1 - 1] == word2[len2 - 1];
  int cost = lastCharsEqual ? 0 : 1;

  // Remove the last character from both strings for
  // the next recursive iteration.
  std::string short1 = word1.substr(0, len1 - 1);
  std::string short2 = word2.substr(0, len2 - 1);

  // Finally, return the minimum edit distance if we
  // remove a character:
  return std::min(std::min(
    led(short1, word2) + 1,    // from word1,
    led(word1, short2) + 1),   // from word2,
    led(short1, short2) + cost // Or from both.
  );
}

Bad Example

int led(std::string word1, std::string word2) {
  int len1 = word1.size();
  int len2 = word2.size();

  if (len1 == 0) return len2;
  if (len2 == 0) return len1;

  bool lastCharsEqual = word1[len1 - 1] == word2[len2 - 1];
  int cost = lastCharsEqual ? 0 : 1;

  std::string short1 = word1.substr(0, len1 - 1);
  std::string short2 = word2.substr(0, len2 - 1);

  return std::min(std::min(
    led(short1, word2) + 1,
    led(word1, short2) + 1),
    led(short1, short2) + cost
  );
}

Line Width

Keep your lines to a reasonable length.

Unfortunately, not everyone codes on an ultrawide monitor.

Good Example

int addFiveNumbers(int num1, int num2, int num3, int num4, int num5) {
  return (num1 + num2 + num3 + num4 + num5);
}

Bad Example

int addFiveNumbers(int num1, int num2, int num3, int num4, int num5) { return (num1 + num2 + num3 + num4 + num5); }