Merge pull request #13 from gonuke/more_style

Added some more simple style guidance

Author: MicahGale

README.md

@@ -46,7 +46,37 @@ if __name__ == "__main__":
 
 ### Variable naming
 * Generally, choose nouns for variables and verbs for methods
+* The most common approach to multi-word variables is "snake case": variables
+  are in lower case with words separated by underscore
 * Clear variable and method names can reduce the need for comments
+* Carefully determine whether temporary variables are helpful. If you only use
+  it once, consider if that line of code can be combined with the place it is
+  used.
+* Avoid **Magic Numbers** - numerical constants without a clear purpose
+    * provide numerical constants with a variable to describe their purpose
+    * these can be physical constants (`AVOGADRO = 6.02e23`), unit conversions
+      (`EV2MEV = 1e-6`), or vector indices (`z = 2`), among others
+    * they are not generally needed for things like squaring a quantity or
+      dividing by some integer that arises from algebra
+
+### Data structure design
+* Take advantage of python's rich data structures and related methods
+* `dictionaries` are a preferred way to bind data together in a way that is
+  clear, rather than parallel lists that are indexed in parallel
+* `numpy` arrays are frequently better choices than python lists for numerical
+  data
+* when looping over iterables (e.g. lists, dictionaries, numpy arrays, etc), 
+  avoid an indexing variable if possible
+    * `zip()` may be useful for iterating through multiple iterables with parallel
+      indexing
+    * `enumerate()` allows you to autogenerate an indexing variable, but make sure you need that index
+    * iterating over a `range()` is probably a last resort, try iterating directly over
+      the iterable or using `zip`
+* consider [list
+  comprehensions](https://www.w3schools.com/python/python_lists_comprehension.asp)
+  for simple operations
+* when using a loop variable, consider the same general guidance on variable naming; 
+  avoid overly simple loop variables, e.g. `(i,j,k)`, that have no semantic meaning
 
 ### Comments
 * Include a docstring in every method
@@ -55,7 +85,23 @@ if __name__ == "__main__":
 
 ### Modularity
 * If you have cut & paste code in two different places, it probably should be a
-  method
+  method/function (or in some cases a loop)
 * Even very short methods can be valuable if the method name makes the code more
   readable
 * Ideally, methods should be no longer than one screen worth of lines
+* Practice **Separation of Concerns**:
+    * a single method should have a single purpose that is clear from the name
+    * avoid any combination of reading, using and writing data in the same
+      method
+
+## Checklist 
+
+Before submitting a PR, ask yourself: "Have I...."
+* [ ] modularized my code into methods that each have a clear and
+  singular purpose?
+* [ ] included a docstring for every method?
+* [ ] replaced all magic numbers with variables?
+* [ ] used method names (verbs) and variable names (nouns) that make the
+  code clearly readable?
+* [ ] removed instances of copy/paste code or nearly identical sections of code?
+* [ ] made good data structure design choices?