Code cleanup.

Clarify comments, improve error messages.
Add an important clarifying comment.