add more comments and rename a couple of badly named variables