Minor refactorings to remove some reek smells on.

Includes adding class comments, renaming variables and removing unused
variables.

For issue #231.
Merge pull request #247 from gilles-leblanc/reek_smell_free

Minor refactorings to remove some reek smells.