   (and (> (impact-force mass velocity) min-impact-force-for-splatter)
        (> (rand) 0.8)))
 
-;; if an impact splatters then we will need to bounce its velocity
-;; vector as this is the direction it will exit its current position
-
-;; the equation to bounce a vector, V, off a plane with normal, N, is:
-;; needs rewriting http://mathworld.wolfram.com/Reflection.html
+;; If an impact splatters then we will need to bounce its velocity
+;; vector as this is the direction it will leave its current position.
+
+;; The equation to bounce a vector, $V$, off a plane with normal, $N$, is:
+;; **needs rewriting http://mathworld.wolfram.com/Reflection.html**
 ;; 
-;;  N is the normal vector of the plane
-;;  R is the reflected vector
+;;    - $N$ is the normal vector of the plane
+;;    - $V$ = the incoming vector
+;;    - $B$ is the outgoing, bounced, vector
 ;; 
-;;  R = V - (2 * (V.N) * N)
-
-;; dot product is he sum of the multiples of the dimensions
+;;  $B = V - (2 * (V.N) * N)$
+
+;; We are missing a few of the required vector operations used in this
+;; equation so we should define some more functions before trying to
+;; implement it. The first is the vector dot product, this is defined
+;; as the sum of the multiples of each dimension. Otherwise we need
+;; substraction of two vectors and a function to multiply a vector by
+;; a constant.
 
 (defn dot-product [vector1 vector2]
   (reduce + (map * vector1 vector2)))

  (map #(* % constant) vector))


;; blah? need a better name for this variable

(defn bounce-vector [vector normal]
  (let [vector-dot-normal (dot-product vector normal)
        blah (vector-multiply-by-constant normal (* 2 vector-dot-normal))]
    (vector-subtraction vector blah)))


;; splatter will never take all of the paint and velocity with it so
;; we need a dampening constant

(def splatter-dampening-constant 0.7)


        minus-sqrt (/ (- minus-b (Math/sqrt discriminant)) (* 2 a))]
    (max add-sqrt minus-sqrt)))

;; We can calculate the time but we want the final position and
;; velocity. For position we can use the same function that we
;; rearranged above to derive the time.

(defn position-at [time initial-position initial-velocity acceleration]
  (+ initial-position
     (* initial-velocity time)
     (/ (* acceleration time time) 2)))

;; For velocity we can use another equation of motion:
;;
;; $v = at + v0$

(defn velocity-at [time initial-velocity acceleration]
  (+ (* acceleration time) initial-velocity))


;; These functions we just implemented can be joined up to get given
;; an initial position and velocity and return the final position and
;; velocity. This function doesn't explicitly ask for the acceleration
;; on the paint, it assumes only gravity is acting on it and uses the
;; constant defined earlier on.

(defn project-point [position velocity]
  (let [[i j k]            position
