adding lots of comments, some refactoring for more clear choice of variable names