adding explanatory comments and a bit of logging