Clean_Code_Guide.md

General Guidelines for Clean Code

NOTE: There is no right and wrong to style.

Style is likely the most subjective feature of programming, even writing in general, and as such, any guide on this topic should be taken with a grain of salt. These suggestions are personallized to me (@bjrice13) such that I write code meaningful to me.

With that in mind, everyone should adopt their own style best fit for their own personal use, meaning everyone's styles will vary.

Several of these suggestions have been adopted from this very polarizing video.

1. "Signal-to-noise Ratio": Don't Write Unused or Unuseful Code

Any code statement, i.e. variable, class, or function, that is not directly used by the program should be omitted.

Comments are incredibly important, but are also easily misused. Don't write a comment that simply puts the code statement into words. Rather, write comments that elaborate on the meaning or use of the code. Misleading comments can confuse any readers.

2. Spacing and formatting: Don't Mix Styles

• Typically, each line of code should be concise and not extend past column 80.

• Always put the opening brace following an argument list on a new line.

• Proper indentation is key! Try to allign code such that "child" lines of code don't overlap with their "parent" lines' allignments.

3. Useful Naming: Short and Sweet

• Try to name variables, classes, functions, etc., in a concise but direct manner.

• The purpose of naming is facilitate communication between the author and other authors or readers by giving the object meaning.

• Use comments whenever the name doesn't absolutely convey the object's meaning or use.

Example:

Don't Do:

/*
 *  poorlyWrittenCode.cpp
 *
 *  Author: Brandon Rice
 *  Date: 8-3-2018
 *  Use: To show how much noise and confusion can be generated by poorly written code
 *  Language: C++
 *  Type: Source file
 *  Status: Unfinished
 *  Copyright (c) 2018
 */
 
#include <iostream>
using namespace std;

class myFirstClass {
    private:
        int a;
    public:
        double b;
        
    myFirstClass() {
        a=5;
        b=2;
        b=a+b;
    }
};

/* I love to eat pie, so thisFunctionIsVeryUseless adds apple pies and blueberry
 * pies together. This function is cool and is VERY!!! important.
 */
int thisFunctionIsVeryUseless(int a, int b, double x, int theNumberOfTimesTheCodeShouldBeIterated) {
    
    //////////////////////////////////////////////////////////////////////
    //                                                                  //
    //                          Add one to a                            //
    //                                                                  //
    //////////////////////////////////////////////////////////////////////
    
    a = a+1;
    
    //////////////////////////////////////////////////////////////////////
    //                                                                  //
    //                          Add five to b                           //
    //                                                                  //
    //////////////////////////////////////////////////////////////////////
    
    b = b+5;
    
    x = a+b;    // Set x to the sum of a and b
    
    for(int i=0;i<theNumberOfTimesTheCodeShouldBeIterated;i++)
    {
        // Do nothing; waste some space
    }
    
    return x;   
}

int main() 
{
    int p;  // Declare p
    
    p = thisFunctionIsVeryUseless(1,2,3,4); // Set p to thisFunctionIsVeryUseless(1,2,3,4)
    
    return 0;   // Exit the program with code 0
}

// End of program

Do:

/*
 *  Author: Brandon Rice
 *  Creation Date: 8-14-2018
 *  Use: To show how reducing noize can reduce confusion
 *  Copyright (c) 2018
 */
 
#include <iostream>
using namespace std;

const int applesPerPie = 5; // From research

class Tree
{
    public:
        int apples;         // Number of apples on tree
        
    Tree()
    {
        apples = 20;
    }
};


/* 
 * Calculates how many apple pies can be made from picking the apples on the tree
 */
int calcApplePies(int applesAvailable) {
    
    int numPies = applesAvailable / applesPerPie;
    
    return numPies;
}


int main() 
{
    Tree appleTree;
    int pies;               // Number of pies able to make
    
    pies = calcApplePies(appleTree.apples);
    
    cout << "I can make " << pies << " pies." << endl;
    
    return 0;
}