Improve code comments

To avoid technical debt and share our knowledge across the team - we need to practice good documentation. 

Please ensure that class has a preamble that describes the purpose of the class and high-level functionality.

Methods that are no-trivial should have a short comment outline their purpose and "business" logic that they encapsulate.
