Exercise: Knows why comments lie, and how to write self-documenting code

gistfile1.txt

1. Take a break from the exercises for a bit. Explain why we say that 'comments lie'.

Comments often "lie" because the code they explain often changes down the road, either
through bug fixes, refactorings, or updates. The person making the changes
may either forget to update the comment, or neglect them because they aren't
a high priority. Either way, the comment doesn't adequately reflect what the code
does, and thus, "lies".

2. If we don't trust comments, how do we explain our code adequately to others?

 - First, our code should have intention-revealing names, both for variables and methods. 
 This goes a long way to eliminating the need for comments. 

 - Second, well-structured tests serve as good documentation of how the code is
 intended to work. Not only do they cover the basic cases of the code, but also
 the edge cases, and thus can explain the nuaces of how the code should work to others.
 In addition, this form of "documentation" will always reflect the underlying code, 
 assuming the tests are run each time changes are made.

3. Explain what 'self documenting code' means in your own words

In my opinion, "self documenting code" is code that reads like a book. The
intention of the code is obvious, because of well-chosen variable and method
names, combined with idiomatic and simple methods. On the whole, the code strives 
for simplicity and clarity, and its purpose is quickly understood by others.