Chapter 5 - Formatting

• The point of formatting is so that everyone who reads the code is able to do with ease in a way that is comfortable.
• Reading code can be comfortable when there is a standard way of laying out the code so that you know what to expect... formatting.
• Formatting is crucial for the longevity of your code.
• Although formatting is super important, it is nothing worth losing sleep over.

Vertical Formatting

• A source file should be similar to a newspaper article, a short nice header that gives a good enough idea of what the module is for.
• Detail should increase downward until we reach the lowest level functions.

Vertical Openness Between Concepts

• We want to have blank lines separating functions and distinct areas of our code, otherwise it can look very cluttered and hard to find distinct points of code.

// Example without spacing
class myClass {
    var myVar = 2;
    var otherVar = 3;
    function func1{
       return null
    }
     function func2{
       return null
    }
     function func3{
       return null
    }
    function func4{
       return null
    }
}

// Example with spacing
class myClass {

    var myVar = 2;
    var otherVar = 3;

    function func1{
       return null
    }

     function func2{
       return null
    }

     function func3{
       return null
    }

    function func4{
       return null
    }
}

Vertical Density

• Lines of code that are closely related should be vertically dense.
• Mundane or useless comments can make code harder to read by making code that should be close to each other less dense.

Vertical Distance

• Functions and variables that are related to each other shouldn't be far away from each other.
• This avoids scrolling around through the file looking for stuff.
• Variable Declarations should be declared as close to where they are going to be used as possible.
• Instance Variables should declared at the top of the class (it doesn't matter if you prefer them at the bottom but they should at least all be together in a well known place.)
• Dependent Functions: If one function calls another they should be vertically close, the caller being above the callee.
• Conceptual Affinity: certain parts of code should be near each other, regardless of if they call each other or not. A good example is if functions are performing similar tasks, they should all be close to each other.

  public class Assert {
      static public void assertTrue(){}
      static public  void assertFalse(){}
  }
  

  • Here I've left the bodies blank but say they don't interact with each other at all.
  • They should still be close because conceptually they are doing very similar things.

Horizontal Formatting

• Some common way for using horizontal openness and density include:
  • Whitespace on the left and right of lower precedence operators to make the left and right operands obvious to see. (=, +, -)
  • No whitespace between higher order operands so that it is easy to see that they are closely related and will operated on first (*, /, %)
  • No white space for a negative variable -a
  • Whitespace after commas to easily see each parameter, argument, etc.
  • No whitespace between char and parentheses.

  // Don't worry. I've made this up just to demonstrate the horizontal spacing
  var equation = (-b + f(1, 2, 3*9)/2 - a)
  

Horizontal Alignment

• refers to aligning items via tabbing so that certain parts all line up.

• an example is below, note that this is not recommended as it brings attention to the wrong areas.

  var     var1;
  var     longerVar;
  var     var2;
  let     anotherOne;
  
  var1 =          2;
  var2 =          var1;
  anotherOne =    45;
  

Indentation

• Is crucial for visually seeing and identifying scope and hierarchy.
• Although it can sometimes be tempting to collapse scopes due to it being very short, this is not recommended.
• If you have a dummy scope, be sure to make it clear with some form of indentation.
  • for example indent the closing semi-colon.

  while(dis.read(buf, 0, readBufferSize) != -1)
      ;
  

Team Rules

• Its normal for programmers to have their own set of rules for formatting that they like.
• It's important to have a uniform set of rules when working in a team so that all code is formatted the same.

Return