clarifying comments, some refactoring to allow more logic method calls