Discussion on: Don't document your code. Code your documentation.

[edA‑qa mort‑ora‑y]

There are a few reasons why I consider comments important:

• languages are ambiguous, or lacking in semantic clarity. A perfectly formed algorithm may not always reveal what it's attempting to do, rather only how it is done.
• How something is done, or what is happening, is not always enough to understand why the function would be called in the first place. Though I agree with nice function names, I disagree with names that are 80-100 characters long. Short of those lengths there will always be some uncertainty in the function's purpose.
• Functions don't live on their own, they exist in a framework. Describing how this function fits into the framework is something that code alone cannot always do. This becomes more important as frameworks become more generic or abstract.