The Art of Readable Code

## Surface-Level Improvements
* Choose Specific Words
  * send -> deliver, dispatch, announce, distribute, route
  * find -> search, extract, locate. recover
  * start -> launch, create, begin, open
  * make -> create, set up, build, generate, compose, add, new
* Avoid Generic Names
  * retval -> sum_squares, etc.
  * tmp -> tmp_file
  * i, j, k -> menbers_i
* Values with Units
  * start -> start_ms
  * password -> plaintext_password
  * data -> data_urlenc
* Length of Name
  * Shoter Names Are Okay for Shoter Scope
* Use Name Formatting to Convey Meaning
  * Class Names -> CamelCase
  * Variable Names -> lower_separated
  * Constant Values -> CamelCase
  * Class Menver Variables -> End with _

## Names That Can't Be Misconstrued
* Prefer First and Last For Inclusive Ranges
  * Use first/last, instead of start/end
* Naming Booleans
  * is, has, can or should
* Avoid Negated Terms
  * disable_ssl -> use_ssl
* Beware of User's Expectation
  * Users may expect get(), size() to be lightweight methods

## Knowing What to Comment
* What NOT to Comment
  * Comment, if commented code is much faster
* Include Director Commentary
* Comment the Flaws in Your Code
  * TODO: Stuff I haven't gotten around to yet
  * FIXME: Known-broken code here
  * HACK: Admittedly inelegant solution to a problem
  * XXX: Danger! major problem here
* Comment on Your Constants
  * Why did you choose the value.
  * isn't important / is highly tuned
* Big Picture Comments
 	* Use sentences as a comment, if you need

## Making Comments Precise and Comapce
* Describe Function Behavior Precisely
 	* Return the number of lines in this file. -> Count how many newline bytes ('/n') are in the file.
* Use Input/Output Examples That Illustrate Corner Cases
 	* Show Examples on Comment
* Named Function Parameter Comments
 	* Use Inline Comment when Call a Function

## Simplifying Loops and Logic

## Making Controle Flow Easy to Read
* The Order of Arguments in Conditionals
 	* Left-hand Side: The expression "being interrogated" whose value is more in flux
  * Right-hand Side: The expression being compared against, whose value is more consitant.
 	* e.g. bytes_received < bytes_expected
* Yoda Notation
 	* To avoid the expression if(obj = NULL)
 	* Not `if(obj == NULL)`, `if(NULL == obj)`
* The Order of if/else Blocks
 	* Prefer dealing with the positive case first
  * Prefer dealing with the simpler case first
  * Prefer dealing with the more interesting or conspicuous
* Conditional Expression ( Ternary Operator)
 	* Instead of minimizing the number of lines, a better metric is to minimize the time needed for someone to understand it.
  * By default, use an if/else. The ternary should be used only for the simplest cases.
* Avoid do/while Loops
* Returning Early from a Function
 	* Use return statements
* Minimize Nesting
 	* By Returning Early
* Removing Nesting Inside Loops
 
## Breaking Down Giant Expressions
* Explaining Variables
 	* username = line.split(':').strip()
* Summary Variables
  * `final boolean users_owns_document = (request.user.id == document.own_id);`
* Using De Morgan's Laws
* Breaking Down Giant Statements
 	* DRY(Don't Repeat Yourself)

## Variables and Readability
* Eliminating Intermidiate Results
* Shrink the Scope of Your Variables
  * Make your variable visible by as few lines of code as possible
  	* Don't use "mini-global" which means class member variable. Demote to be a local variable.
 	* Make as many methods static as possible
 	* Break the large class into smaller classes
* if Statement Scope
  * `if(PaymentInfo* info = database.ReadPaymentInfo())`

* JavaScript Global Scope
 	* If you omit the `var`, the variables can be accessed from every JavaScript file.
 	* Always use `var`
 
## Reorganizing Your Code
## Extracting Unrelated Subproblems
* Other Genearal-Purpose Code


```JavaScript:format_pretty(JavaScript)
   var format_pretty = function(obj, indent){
     //Handle null, undefined, string, and non-objects.
     if(obj == null) return "null";
     if(obj == undefined) return "undefined";
     if(typeof obj == "string") return '"' + obj + '"';
     if(typeof obj !== "object") return String(obj);
     
     if(indent == undefined) indent = "";
     
     //Handle (non-null) objects.
     var str = "{\n";
     for(var key in obj){
       str += indent + " " + key + " = ";
       str += format_pretty(obj[key], indent + " ") + "\n";
     }
     return str + indent + "}";
   }
```


```Python:make_url_friendly(Python)

   CHARS_TO_REMOVE = re.compile(r"[''/.]+")
   CHARS_TO_DASH = re.compile(r"[^a-z0-9]+")
   
   def make_url_friendly(text):
     text = text.lower()
     text = CHARS_TO_REMOVE.sub('', text)
     text = CHARS_TO_DASH.sub('-', text)
     return text.strip('-')
```

## One Task at a Time
* One Task at a Time
 	* List out all the "tasks" your code is doing.
  * Try to separeta those tasks as much as you can into differenet functions or at least different sections of code.
  * Tips: `first_half = town || city || "Default Value"`
## Turning Thoughts into Code
* An English Description of the Solution
	* If you can't describe the problem or your design in words, something is probably missing or undefined.

## Writing Less Code
* Keeping Your Codebase Small
* Be Familiar with the Libraries Around You
 	* Every once in a while, spend 15 minutes reading the names of all functions/modules/types in your standard library.

## Selected Topics
## Testing and Readbility
* Using Better Versions of aeert()

```Python:assert()
import unittest
assertEqual(a, b)
```
   
* Multiple Tests of Functionality
* Naming Test Functions
 	* Don't be afraid of having a long or cluncky name.
* Test-Friednly Development
 	* Class have little or no internal state
  * Classes/functions only do one thing
  * Classes depend on few other classes; high decoupling 
  * Functions have simple, well-defined interfaces