Document Every Function

[edvb]

Every function should have a short doc string describing what it does.

Code should also be well commented. Any nontrivial line (or group of lines) should have a short explanation of what it does if the code is not self-explanatory, but more importantly, should always describe why it does it this way.