some small refactorings. adding docblocks. creating guard clauses. refactor our some code into methods. no aditional test failures so it looks ok. also added some @todo comments